@vailix/mask 0.1.2

package/BLE_IMPLEMENTATION_PLAN.md

@@ -0,0 +1,703 @@
+# BLE Implementation Plan: Replace NFC with Bluetooth Low Energy
+
+**Date:** January 7, 2026  
+**Status:** Draft for Review  
+**Scope:** Replace NFC pairing in `@vailix/mask` with BLE-based proximity exchange
+
+---
+
+## 1. Overview
+
+### Current State (NFC)
+- Phone-to-phone NFC exchange doesn't work reliably on modern devices
+- iOS cannot emulate NFC tags (Apple restriction)
+- Requires 2-3 taps with physical NFC tags
+
+### Proposed State (BLE)
+- Foreground-only BLE advertising and scanning
+- One-tap pairing with explicit user consent
+- Cross-platform (iOS + Android)
+- No physical hardware required
+
+---
+
+## 2. User Flow
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  USER A                           USER B                    │
+├─────────────────────────────────────────────────────────────┤
+│  1. Opens app                     1. Opens app              │
+│     ↓                                ↓                      │
+│  2. App starts advertising        2. App starts advertising │
+│     + scanning                       + scanning             │
+│     ↓                                ↓                      │
+│  3. Sees "🐼 42" in               3. Sees "🦊 17" in        │
+│     nearby list                      nearby list            │
+│     ↓                                                       │
+│  4. Taps "🐼 42" to pair                                    │
+│     ↓                                ↓                      │
+│  5. BLE connection established ←→ Connection accepted       │
+│     ↓                                ↓                      │
+│  6. Exchanges RPI + metadataKey  ←→ Exchanges RPI + metaKey │
+│     ↓                                ↓                      │
+│  7. Both phones now have each other's data ✓                │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**Total user actions:** 1 tap (by either user)
+
+---
+
+# PART A: Package Implementation (`@vailix/mask`)
+
+This section covers changes to the `@vailix/mask` package source code.
+
+---
+
+## 3. Package Dependencies
+
+### Add to `packages/mask/package.json`
+```json
+{
+  "dependencies": {
+    "react-native-ble-plx": "^3.2.1"
+  }
+}
+```
+
+### Remove from `packages/mask/package.json`
+```json
+{
+  "dependencies": {
+    "react-native-nfc-manager": "^3.14.0"  // REMOVE
+  }
+}
+```
+
+---
+
+## 4. File Changes
+
+### Files to Delete
+```
+src/nfc.ts                    # Remove entirely
+```
+
+### Files to Create
+```
+src/ble.ts                    # New BLE service
+```
+
+### Files to Modify
+```
+src/index.ts                  # Replace NFC methods with BLE methods
+src/types.ts                  # Add BLE-related types
+package.json                  # Update dependencies
+README.md                     # Update documentation
+```
+
+---
+
+## 5. BLE Service Design (`src/ble.ts`)
+
+### 5.1. Constants
+```typescript
+// Service UUID (unique to Vailix - generate once, use forever)
+const VAILIX_SERVICE_UUID = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890';
+
+// Characteristic UUIDs
+const RPI_OUT_CHAR_UUID = 'a1b2c3d4-e5f6-7890-abcd-ef1234567891'; // Others read my RPI from here
+const RPI_IN_CHAR_UUID = 'a1b2c3d4-e5f6-7890-abcd-ef1234567892';  // Others write their RPI to here
+
+const META_OUT_CHAR_UUID = 'a1b2c3d4-e5f6-7890-abcd-ef1234567893'; // Others read my Key from here
+const META_IN_CHAR_UUID = 'a1b2c3d4-e5f6-7890-abcd-ef1234567894';  // Others write their Key to here
+
+// Default timeout before removing user from nearby list
+const DEFAULT_DISCOVERY_TIMEOUT_MS = 15000; // 15 seconds
+```
+
+### 5.2. Types (add to `src/types.ts`)
+```typescript
+/**
+ * Represents a nearby user discovered via BLE.
+ * 
+ * Design: Internal details (RPI, metadataKey) are hidden from the public API.
+ * The app only needs: something to display, something to pair with, and status flags.
+ * RPIs and keys are managed internally by the package for contact tracing.
+ */
+export interface NearbyUser {
+  id: string;              // Opaque identifier for pairing (pass to pairWithUser)
+  displayName: string;     // Generated emoji + number for UI display
+  rssi: number;            // Signal strength (for proximity filtering)
+  discoveredAt: number;    // Timestamp of last advertisement received
+  paired: boolean;         // true if we have securely stored their data
+  hasIncomingRequest: boolean; // true if they sent us data but we haven't accepted yet (explicit mode)
+}
+
+// Internal type (not exported) - used by BleService
+interface InternalNearbyUser extends NearbyUser {
+  rpiPrefix: string;       // Truncated RPI from advertisement (8 bytes hex)
+  fullRpi?: string;        // Complete RPI (populated after GATT read)
+  metadataKey?: string;    // Metadata key (populated after GATT read)
+}
+
+/**
+ * Design Decision: Why hide RPI/metadataKey from public API?
+ * 
+ * 1. Cleaner API - App developers don't need to understand contact tracing internals
+ * 2. Prevents misuse - Can't accidentally expose RPIs in logs or analytics
+ * 3. Two-phase data - rpiPrefix available on discovery, fullRpi only after pairing
+ * 4. Future flexibility - Internal structure can change without breaking apps
+ */
+
+export interface PairResult {
+  success: boolean;
+  partnerRpi?: string;
+  partnerMetadataKey?: string;
+  error?: string;
+}
+
+// Unified Configuration Interface
+export interface VailixConfig {
+  // --- Backend & Auth ---
+  reportUrl: string;
+  downloadUrl: string;
+  appSecret: string;
+  
+  // --- Storage ---
+  keyStorage?: KeyStorage;
+  reportDays?: number;
+
+  // --- Contact Tracing Protocol ---
+  rpiDurationMs?: number;
+  rescanIntervalMs?: number;
+
+  // --- BLE Proximity & Pairing ---
+  // Timeout before removing a user from nearby list (default: 15000ms)
+  bleDiscoveryTimeoutMs?: number; 
+  
+  // Minimum RSSI to consider a user "nearby" (default: -70)
+  proximityThreshold?: number;
+  
+  // If true, automatically pair when receiving a write (default: true)
+  // If false, set hasIncomingRequest=true and wait for explicit pairWithUser()
+  autoAcceptIncomingPairs?: boolean;
+}
+```
+
+### 5.3. BleService Class
+```typescript
+// src/ble.ts
+
+import { BleManager, Device, State } from 'react-native-ble-plx';
+import { VailixConfig } from './types';
+
+// Internal service configuration derived from main config
+export interface BleServiceConfig {
+  discoveryTimeoutMs?: number;   // Default: 15000
+  proximityThreshold?: number;   // Default: -70
+  autoAccept?: boolean;          // Default: true
+}
+
+export class BleService {
+  private manager: BleManager;
+  private isAdvertising: boolean = false;
+  private isScanning: boolean = false;
+  private nearbyUsers: Map<string, InternalNearbyUser> = new Map(); // Internal type with RPI details
+  private discoveryTimeoutMs: number;
+  private proximityThreshold: number;
+  private autoAccept: boolean;
+  private cleanupInterval?: NodeJS.Timeout;
+  private onNearbyUpdated?: (users: NearbyUser[]) => void; // Public type (no RPI details)
+
+  constructor(config: BleServiceConfig = {}) {
+    this.manager = new BleManager();
+    this.discoveryTimeoutMs = config.discoveryTimeoutMs ?? DEFAULT_DISCOVERY_TIMEOUT_MS;
+    this.proximityThreshold = config.proximityThreshold ?? -70;
+    this.autoAccept = config.autoAccept ?? true;
+  }
+
+  // Check if BLE is available and enabled
+  async initialize(): Promise<boolean>;
+
+  // Start advertising our RPI + scanning for others
+  async startDiscovery(myRpi: string, myMetadataKey: string): Promise<void>;
+
+  // Stop advertising and scanning
+  async stopDiscovery(): Promise<void>;
+
+  // Get current list of nearby users
+  getNearbyUsers(): NearbyUser[];
+
+  // Subscribe to nearby user updates
+  onNearbyUsersChanged(callback: (users: NearbyUser[]) => void): () => void;
+
+  // Initiate pairing with a specific user (triggers bidirectional exchange)
+  async pairWithUser(userId: string, myRpi: string, myMetadataKey: string): Promise<PairResult>;
+
+  // Cleanup resources
+  destroy(): void;
+}
+```
+
+### 5.4. Display Name Generation
+```typescript
+// Generate random emoji + number for anonymous identification
+const EMOJIS = ['🐼', '🦊', '🐨', '🦁', '🐯', '🐸', '🦋', '🐙', '🦄', '🐳'];
+
+function generateDisplayName(rpiPrefix: string): string {
+  // Deterministic based on truncated RPI (from advertisement)
+  // Ensures all scanners see the same name for the same user
+  // 8 bytes (64 bits) provides plenty of entropy for 1000 combinations
+  const hash = rpiPrefix.split('').reduce((a, b) => a + b.charCodeAt(0), 0);
+  const emoji = EMOJIS[hash % EMOJIS.length];
+  const number = hash % 100;
+  return `${emoji} ${number}`;
+}
+```
+
+### 5.5. Stale User Cleanup
+```typescript
+// Remove users not seen within timeout period
+private startCleanupInterval(): void {
+  this.cleanupInterval = setInterval(() => {
+    const now = Date.now();
+    let changed = false;
+    
+    for (const [id, user] of this.nearbyUsers) {
+      if (now - user.discoveredAt > this.discoveryTimeoutMs) {
+        this.nearbyUsers.delete(id);
+        changed = true;
+      }
+    }
+    
+    if (changed && this.onNearbyUpdated) {
+      // Strip internal fields before emitting
+      this.onNearbyUpdated(Array.from(this.nearbyUsers.values()).map(this.toPublicUser));
+    }
+  }, 1000); // Check every second
+}
+
+// CRITICAL: When a device is discovered via scanning:
+// 1. If it's a NEW device: Add to map with current timestamp
+// 2. If it's an EXISTING device: Update `rssi` AND `discoveredAt` = Date.now()
+// This ensures active users are not removed by the cleanup interval.
+
+// When emitting to onNearbyUpdated callback, strip internal fields:
+// InternalNearbyUser -> NearbyUser (remove rpiPrefix, fullRpi, metadataKey)
+private toPublicUser(internal: InternalNearbyUser): NearbyUser {
+  const { rpiPrefix, fullRpi, metadataKey, ...publicFields } = internal;
+  return publicFields;
+}
+```
+
+### 5.6. Advertisement Data Structure
+
+BLE advertisement payload (max ~31 bytes for legacy):
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ Field           │ Size    │ Description                 │
+├─────────────────┼─────────┼─────────────────────────────┤
+│ Service UUID    │ 16 bytes│ VAILIX_SERVICE_UUID         │
+│ RPI (truncated) │ 8 bytes │ First 8 bytes of RPI        │
+│ Flags           │ 1 byte  │ Protocol version, etc.      │
+└─────────────────────────────────────────────────────────┘
+```
+
+Full RPI + metadataKey exchanged via GATT characteristics after connection.
+
+### 5.7. GATT Service Structure
+
+```
+Vailix Service (VAILIX_SERVICE_UUID)
+├── RPI_OUT (RPI_OUT_CHAR_UUID)
+│   ├── Properties: Read
+│   └── Value: 32 bytes (My RPI)
+│
+├── RPI_IN (RPI_IN_CHAR_UUID)
+│   ├── Properties: Write
+│   └── Value: - (Incoming RPIs)
+│
+├── META_OUT (META_OUT_CHAR_UUID)
+│   ├── Properties: Read
+│   └── Value: 64 bytes (My Metadata Key)
+│
+└── META_IN (META_IN_CHAR_UUID)
+    ├── Properties: Write
+    └── Value: - (Incoming Metadata Keys)
+```
+
+---
+
+## 6. SDK API Changes (`src/index.ts`)
+
+### 6.1. New Config Option
+
+Add `bleDiscoveryTimeoutMs` to `VailixSDK.create()` config:
+
+```typescript
+// Consolidated create method using the new unified config interface
+static async create(config: VailixConfig): Promise<VailixSDK>
+```
+
+### 6.2. Remove NFC Methods
+```typescript
+// REMOVE these from VailixSDK:
+static async isNfcSupported(): Promise<boolean>;
+async pairViaNfc(): Promise<{ success: boolean; partnerRpi?: string }>;
+```
+
+### 6.3. Add BLE Methods
+```typescript
+// ADD these to VailixSDK:
+
+// Start BLE discovery (call when pairing screen opens)
+async startDiscovery(): Promise<void>;
+
+// Stop BLE discovery (call when leaving pairing screen)
+async stopDiscovery(): Promise<void>;
+
+// Get list of nearby users
+getNearbyUsers(): NearbyUser[];
+
+// Subscribe to nearby user updates (returns cleanup function)
+onNearbyUsersChanged(callback: (users: NearbyUser[]) => void): () => void;
+
+// Pair with a specific user (one-tap action, or accept incoming request)
+async pairWithUser(userId: string): Promise<{ success: boolean; partnerRpi?: string }>;
+
+// Unpair with a user (removes from storage and resets status)
+async unpairUser(userId: string): Promise<void>;
+
+// Check if BLE is available
+static async isBleSupported(): Promise<boolean>;
+```
+
+---
+
+## 7. Pairing Handshake Protocol
+
+When User A taps to pair with User B:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ Step │ Action                                               │
+├──────┼──────────────────────────────────────────────────────┤
+│  1   │ A connects to B's GATT server                        │
+│  2   │ A reads B's RPI_OUT → gets B's RPI                   │
+│  3   │ A reads B's META_OUT → gets B's key                  │
+│  4   │ A writes A's RPI to B's RPI_IN                       │
+│  5   │ A writes A's MetadataKey to B's META_IN              │
+│  6   │ B receives write on IN chars → processing logic      │
+│  7   │ A stores B's RPI + key locally                       │
+│  8   │ A disconnects                                        │
+│  9   │ Both phones now have each other's data ✓             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**Result:** Single tap by A triggers mutual exchange.
+
+### 7.1. Paired Status Update & Explicit Consent
+
+**Configuration:** `autoAcceptIncomingPairs` (boolean)
+
+**Scenario A: User initiates pairing (Always Explicit for Initiator)**
+1. User A taps pair on User B
+2. Exchange completes
+3. A stores B's data -> `paired = true`
+
+**Scenario B: User receives pairing (Passive Role)**
+
+*If `autoAcceptIncomingPairs = true` (Default):*
+1. Package receives write -> Validates data
+2. Package stores A's data securely
+3. Sets `nearbyUsers[A].paired = true`
+4. App shows "Paired"
+
+*If `autoAcceptIncomingPairs = false` (Explicit Mode):*
+1. Package receives write -> Validates data
+2. Package *holds* data in memory (does NOT persist to secure storage yet)
+3. Sets `nearbyUsers[A].hasIncomingRequest = true` (and `paired = false`)
+4. App shows "Accept?" button or indication for User A
+5. User B taps "Accept" (calls `pairWithUser(A)`)
+6. `pairWithUser` finds pending data -> Persists to secure storage
+7. Sets `paired = true`, `hasIncomingRequest = false`
+8. App shows "Paired"
+
+**Unpairing (`unpairUser`)**
+- Deletes RPI + MetadataKey from secure storage
+- Updates `nearbyUsers` list: sets `paired = false`, `hasIncomingRequest = false`
+- Allows user to "undo" a pairing or reject a request
+
+### 7.2. Race Condition Handling
+
+If both users tap "pair" simultaneously:
+- Both phones attempt to connect to each other
+- Both exchanges may happen in parallel (redundant but safe)
+- One connection might fail while the other succeeds
+
+**Mitigation:** After a failed `pairWithUser()`, check if we already have that user's RPI stored (from the reverse connection). If yes, return success anyway.
+
+```typescript
+async pairWithUser(userId: string): Promise<PairResult> {
+    try {
+        // Attempt connection and exchange
+        const result = await this._doExchange(userId);
+        return result;
+    } catch (error) {
+        // Check if we already have this user's RPI (paired via reverse connection)
+        const internalUser = this.nearbyUsers.get(userId); // InternalNearbyUser
+        if (internalUser?.fullRpi) {
+            const alreadyPaired = await this.storage.hasRpi(internalUser.fullRpi);
+            if (alreadyPaired) {
+                return { success: true, partnerRpi: internalUser.fullRpi };
+            }
+        }
+        return { success: false, error: error.message };
+    }
+}
+```
+
+---
+
+## 8. Package-Level Security
+
+### 8.1. Proximity Filtering (optional, configurable)
+```typescript
+// Only show users within reasonable proximity
+// Configurable via `proximityThreshold` (default: -70)
+const MIN_RSSI = -70; // Approximately 1-2 meters
+
+function filterByProximity(users: NearbyUser[]): NearbyUser[] {
+  return users.filter(u => u.rssi >= MIN_RSSI);
+}
+```
+
+### 8.2. Replay Protection
+- RPI changes periodically (configured via `rpiDurationMs`)
+- Timestamp included in stored scan data
+- Old RPIs rejected during matching
+
+### 8.3. Connection Security
+- BLE connections are not encrypted by default at the application layer
+- Data exchanged (RPI + metadataKey) is already designed to be shared
+- No sensitive user data is transmitted
+
+### 8.4. Rate Limiting
+- Rate limit connection attempts to prevent abuse
+- Timeout stale nearby users based on `discoveryTimeoutMs`
+
+---
+
+## 9. Implementation Order
+
+1. **Phase 1:** Add `react-native-ble-plx` dependency, create `src/ble.ts` skeleton
+2. **Phase 2:** Implement advertising + scanning
+3. **Phase 3:** Implement GATT server (peripheral role)
+4. **Phase 4:** Implement connection + data exchange (central role)
+5. **Phase 5:** Integrate into VailixSDK, update `src/index.ts`
+6. **Phase 6:** Remove NFC code and `react-native-nfc-manager` dependency
+7. **Phase 7:** Update types, exports, and README
+8. **Phase 8:** Testing
+
+---
+
+## 10. Breaking Changes & Versioning
+
+### 10.1. Breaking Changes
+- `pairViaNfc()` removed
+- `isNfcSupported()` removed
+- New methods: `startDiscovery()`, `stopDiscovery()`, `pairWithUser()`, etc.
+
+### 10.2. Version Bump
+- This is a **breaking change** → bump to `v0.2.0`
+
+### 10.3. Changelog Entry
+```markdown
+## [0.2.0] - 2026-01-XX
+
+### Changed
+- **BREAKING:** Replaced NFC pairing with BLE-based proximity discovery
+- **BREAKING:** New unified `VailixConfig` interface for SDK configuration
+- New API: `startDiscovery()`, `stopDiscovery()`, `pairWithUser()`, `onNearbyUsersChanged()`
+- Removed: `pairViaNfc()`, `isNfcSupported()`
+
+### Added
+- `NearbyUser` type for discovered users (with `paired` and `hasIncomingRequest` status flags)
+- `isBleSupported()` static method
+- `unpairUser()` method to remove a pairing
+- Config options:
+  - `bleDiscoveryTimeoutMs` - timeout for stale user removal (default: 15000)
+  - `proximityThreshold` - minimum RSSI for nearby filtering (default: -70)
+  - `autoAcceptIncomingPairs` - auto-accept or explicit consent mode (default: true)
+
+### Removed
+- `react-native-nfc-manager` dependency
+- NFC-related code (`src/nfc.ts`)
+```
+
+---
+
+# PART B: App Developer Integration (README Documentation)
+
+This section covers what app developers need to do when using `@vailix/mask`.
+These items should be documented in the package README, not implemented in the package.
+
+---
+
+## 11. App Configuration (Developer Responsibility)
+
+### 11.1. iOS Configuration
+
+App developer must add to `ios/[AppName]/Info.plist`:
+
+```xml
+<key>NSBluetoothAlwaysUsageDescription</key>
+<string>Used to discover and pair with nearby users</string>
+<key>NSBluetoothPeripheralUsageDescription</key>
+<string>Used to allow other users to discover you</string>
+```
+
+### 11.2. Android Configuration
+
+App developer must add to `android/app/src/main/AndroidManifest.xml`:
+
+```xml
+<uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
+<uses-permission android:name="android.permission.BLUETOOTH_ADVERTISE" />
+<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
+<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
+```
+
+---
+
+## 12. Usage Example (For README)
+
+```typescript
+// PairingScreen.tsx — Example app implementation
+
+import { useState, useEffect } from 'react';
+import { View, Text, FlatList, TouchableOpacity, Alert } from 'react-native';
+import { NearbyUser } from '@vailix/mask';
+
+function PairingScreen({ sdk }) {
+  const [nearbyUsers, setNearbyUsers] = useState<NearbyUser[]>([]);
+  const [pairingId, setPairingId] = useState<string | null>(null);
+
+  useEffect(() => {
+    // Start discovery when screen opens
+    sdk.startDiscovery();
+
+    // Subscribe to nearby user updates (includes paired status changes)
+    const cleanup = sdk.onNearbyUsersChanged(setNearbyUsers);
+
+    return () => {
+      cleanup();
+      sdk.stopDiscovery();
+    };
+  }, []);
+
+  const handlePair = async (user: NearbyUser) => {
+    setPairingId(user.id);
+    const result = await sdk.pairWithUser(user.id);
+    if (result.success) {
+      Alert.alert('Paired!', `You are now connected with ${user.displayName}`);
+    } else {
+      Alert.alert('Failed', 'Could not pair. Please try again.');
+    }
+    setPairingId(null);
+  };
+
+  return (
+    <View>
+      <Text>Nearby Users ({nearbyUsers.length})</Text>
+      <FlatList
+        data={nearbyUsers}
+        keyExtractor={(item) => item.id}
+        renderItem={({ item }) => (
+          <View style={{ flexDirection: 'row', alignItems: 'center' }}>
+            <Text>{item.displayName}</Text>
+            
+            {/* APP RESPONSIBILITY: Show "Paired" label or "Pair" button based on status */}
+            {item.paired ? (
+              <Text style={{ color: 'green' }}>✓ Paired</Text>
+            ) : (
+              <TouchableOpacity 
+                onPress={() => handlePair(item)} 
+                disabled={pairingId !== null}
+              >
+                <Text>{pairingId === item.id ? 'Pairing...' : 'Pair'}</Text>
+              </TouchableOpacity>
+            )}
+          </View>
+        )}
+      />
+    </View>
+  );
+}
+```
+
+**Key Point:** The `paired` status is managed by the package. The app simply checks `item.paired` to decide whether to show a button or a label.
+
+---
+
+## 13. Edge Cases (App Developer Responsibility)
+
+These scenarios should be handled by the app, not the package:
+
+| Scenario | App Should... |
+|----------|---------------|
+| Bluetooth disabled | Show prompt asking user to enable Bluetooth |
+| Permission denied | Show message with link to Settings |
+| User leaves range mid-pair | Show error toast, allow retry |
+| Multiple users nearby | Display list, let user choose |
+| No users found | Show helpful message ("Ask your partner to open the app") |
+| App backgrounded | Discovery stops automatically; resume when foregrounded |
+
+---
+
+## 14. Testing Plan
+
+### 14.1. Package Unit Tests
+- [ ] BleService initialization
+- [ ] Advertisement data encoding/decoding
+- [ ] Nearby user deduplication
+- [ ] Display name generation
+- [ ] Stale user cleanup logic
+
+### 14.2. Package Integration Tests
+- [ ] Start/stop discovery lifecycle
+- [ ] Pair with mock device
+- [ ] Handle BLE unavailable
+
+### 14.3. Device Testing (App Level)
+- [ ] iOS to iOS pairing
+- [ ] Android to Android pairing
+- [ ] iOS to Android pairing (cross-platform)
+- [ ] Multiple users nearby
+- [ ] Background/foreground transitions
+
+---
+
+## 15. Resolved Questions
+
+1. **User identification:** ✅ Generate random emoji + number from RPI (consistent across all scanners)
+
+2. **Auto-timeout:** ✅ 15 seconds default, **configurable** via `bleDiscoveryTimeoutMs`
+
+3. **Confirmation dialog:** ✅ No confirmation — instant mutual exchange on tap
+
+---
+
+## 16. Approval Checklist
+
+- [ ] Implementation approach approved
+- [ ] API design approved
+- [ ] Breaking change accepted
+- [ ] Package/App separation clear
+
+---
+
+*Ready for review.*