@miller-tech/uap 1.39.0 → 1.40.1

package/docs/deployment/DEPLOY_BATCHER_ANALYSIS.md

@@ -1,224 +0,0 @@
-# DeployBatcher Analysis
-
-Intelligent batching and deduplication for multi-agent deployment scenarios.
-
----
-
-## Overview
-
-The `DeployBatcher` optimizes CI/CD pipeline usage in multi-agent environments through SQLite-backed coordination. Multiple agents queue actions that batch into single CI runs, reducing pipeline minutes by 50-80%.
-
-### Problem Solved
-
-```text
-Without DeployBatcher:
-  Agent A commits → CI Run 1 (5 min)
-  Agent B commits → CI Run 2 (5 min)  
-  Agent C commits → CI Run 3 (5 min)
-  Agent A pushes → CI Run 4 (5 min)
-  Total: 4 runs × 5 min = 20 CI minutes
-
-With DeployBatcher:
-  Agent A, B, C queue commits → Batched → Single squashed commit
-  Total: 1 run × 5 min = 5 CI minutes (75% reduction)
-```
-
----
-
-## Architecture
-
-```mermaid
-flowchart TB
-    subgraph "Multi-Agent Environment"
-        A1[Agent 1]
-        A2[Agent 2]
-        A3[Agent N]
-    end
-
-    subgraph "DeployBatcher Core"
-        Q[Queue Layer]
-        B[Batch Creator]
-        S[Squash Engine]
-        E[Executor]
-    end
-
-    subgraph "Storage"
-        DB[(SQLite DB)]
-        DQ[deploy_queue]
-        DBT[deploy_batches]
-    end
-
-    subgraph "Execution Targets"
-        GIT[Git Operations]
-        GH[GitHub CLI]
-        DEPLOY[Deploy Scripts]
-    end
-
-    A1 --> Q
-    A2 --> Q
-    A3 --> Q
-    
-    Q --> DB
-    DB --> DQ
-    DB --> DBT
-    
-    Q --> B
-    B --> S
-    S --> E
-    
-    E --> GIT
-    E --> GH
-    E --> DEPLOY
-
-    style Q fill:#e3f2fd,stroke:#1976d2
-    style B fill:#fff3e0,stroke:#f57c00
-    style S fill:#c8e6c9,stroke:#388e3c
-```
-
----
-
-## Usage Examples
-
-### Example 1: Multi-Agent Commit Batching
-
-```typescript
-import { DeployBatcher } from './coordination/deploy-batcher.js';
-
-const batcher = new DeployBatcher({ message: 'feat: add user auth',
-  files: ['src/auth.ts', 'src/user.ts']
-});
-
-// Agent 2 commits (within window - will be merged)
-await batcher.queue('agent-2', 'commit', 'main', {
-  message: 'feat: add logging',
-  files: ['src/logger.ts']
-});
-
-// After 30s, create and execute batch
-const batch = await batcher.createBatch();
-const result = await batcher.executeBatch(batch.id);
-
-console.log(result);
-// {
-//   batchId: 'uuid',
-//   success: true,
-//   executedActions: 1,  // Squashed into single commit
-//   failedActions: 0,
-//   duration: 1234
-// }
-```
-
-### Example 2: Urgent Deployment
-
-```typescript
-const batcher = new DeployBatcher();
-
-// Enable urgent mode for critical fix
-batcher.setUrgentMode(true);
-
-// Queue with minimal delay
-await batcher.queue('agent-1', 'commit', 'main', {
-  message: 'hotfix: critical security patch',
-  files: ['src/security.ts']
-}, { urgent: true });
-
-await batcher.queue('agent-1', 'push', 'main', {}, { urgent: true });
-
-// Immediately flush
-const results = await batcher.flushAll();
-
-// Restore normal mode
-batcher.setUrgentMode(false);
-```
-
-### Example 3: Bulk Queue with Transaction
-
-```typescript
-import { DeployBatcher } from './coordination/deploy-batcher.js';
-
-const batcher = new DeployBatcher();
-
-console.log(`Queued ${ids.length} actions`);
-```
-
----
-
-## Performance Characteristics
-
-### Time Complexity
-
-| Operation | Complexity | Notes |
-|-----------|------------|-------|
-| `queue()` | O(1) | Single INSERT |
-| `queueBulk()` | O(n) | Transaction with n INSERTs |
-| `createBatch()` | O(n log n) | SELECT + grouping + squashing |
-| `executeBatch()` | O(n) sequential, O(n/p) parallel | p = maxParallelActions |
-| `flushAll()` | O(b × n) | b batches, n actions each |
-
-### Space Complexity
-
-| Storage | Size |
-|---------|------|
-| Per action | ~500 bytes (JSON payload) |
-| Per batch | ~100 bytes + action references |
-| SQLite overhead | ~4KB per page |
-
-### Recommended Limits
-
-| Parameter | Default | Max Recommended |
-|-----------|---------|-----------------|
-| `maxBatchSize` | 20 | 100 |
-| `maxParallelActions` | 5 | 10 |
-| Queue depth | - | 1000 actions |
-
----
-
-## Database Schema
-
-```mermaid
-erDiagram
-    deploy_queue {
-        INTEGER id PK
-        TEXT agent_id
-        TEXT action_type
-        TEXT target
-        TEXT payload
-        TEXT status
-        TEXT batch_id FK
-        TEXT queued_at
-        TEXT execute_after
-        INTEGER priority
-        TEXT dependencies
-    }
-
-    deploy_batches {
-        TEXT id PK
-        TEXT created_at
-        TEXT executed_at
-        TEXT status
-        TEXT result
-    }
-
-    deploy_queue }o--|| deploy_batches : "belongs to"
-
-    style deploy_queue fill:#e3f2fd,stroke:#1976d2
-    style deploy_batches fill:#fff3e0,stroke:#f57c00
-```
-
----
-
-## Summary
-
-The `DeployBatcher` provides a comprehensive solution for optimizing CI/CD pipeline usage in multi-agent environments:
-
-| Feature | Benefit |
-|---------|---------|
-| Dynamic batch windows | Balances speed vs batching per action type |
-| Commit squashing | Reduces N commits to 1 CI run |
-| Action merging | Deduplicates redundant operations |
-| Parallel execution | Faster batch completion |
-| Urgent mode | Fast path for critical operations |
-| SQLite persistence | Survives agent restarts |
-| CLI integration | Easy manual control |
-
-**Typical CI/CD savings**: 50-80% reduction in pipeline minutes for multi-agent workflows.

package/docs/deployment/DEPLOY_BATCHING.md

@@ -1,273 +0,0 @@
-# Deploy Batching & Bucketing System
-
-## Overview
-
-The UAP Deploy system provides intelligent action batching and execution for automated deployments. It uses **dynamic batch windows** to group related actions together, reducing unnecessary operations and improving efficiency.
-
-## Key Features
-
-### 1. Dynamic Batch Windows
-
-Actions are queued with type-specific waiting periods before being batched together:
-
-| Action Type | Default Window | Description                       |
-| ----------- | -------------- | --------------------------------- |
-| `commit`    | 30,000ms (30s) | Allows squashing multiple commits |
-| `push`      | 5,000ms (5s)   | Fast for PR creation              |
-| `merge`     | 10,000ms (10s) | Moderate safety buffer            |
-| `workflow`  | 5,000ms (5s)   | Fast workflow triggers            |
-| `deploy`    | 60,000ms (60s) | Safety buffer for deployments     |
-
-### 2. Smart Deduplication
-
-The system automatically detects and merges similar actions:
-
-- Multiple commits to the same branch are squashed
-- Multiple pushes to the same branch are merged
-- Duplicate workflow triggers are deduplicated
-
-### 3. Parallel Execution
-
-Independent actions (like workflow triggers) can execute in parallel while maintaining order for dependent actions (commits → push → merge).
-
-### 4. Urgent Mode
-
-For time-critical operations, urgent mode reduces all batch windows to minimum values:
-
-- commit: 2,000ms
-- push: 1,000ms
-- merge: 2,000ms
-- workflow: 1,000ms
-- deploy: 5,000ms
-
-## CLI Commands
-
-### View Current Configuration
-
-```bash
-uap deploy config
-```
-
-**Output:**
-
-```
-📋 Deploy Batch Configuration
-
-Current batch window settings (ms):
-
-  commit:   30000ms   (30s)
-  push:     5000ms   (5s)
-  merge:    10000ms   (10s)
-  workflow: 5000ms   (5s)
-  deploy:   60000ms   (60s)
-```
-
-### Set Custom Configuration
-
-```bash
-uap deploy set-config --message '{"commit":60000,"push":3000,"merge":15000}'
-```
-
-**Examples:**
-
-```bash
-# Set custom windows for all types
-uap deploy set-config --message '{"commit":60000,"push":5000,"merge":10000,"workflow":5000,"deploy":120000}'
-
-# Set only specific windows (others remain unchanged)
-uap deploy set-config --message '{"commit":120000}'
-```
-
-### Enable/Disable Urgent Mode
-
-```bash
-# Enable urgent mode (fast execution)
-uap deploy urgent --on
-
-# Disable urgent mode (return to default windows)
-uap deploy urgent --off
-```
-
-## Usage Examples
-
-### Queue a Deploy Action
-
-```bash
-# Queue a commit action
-uap deploy queue --agent-id my-agent --action-type commit --target main --message "Fix bug" --files src/file.ts
-
-# Queue a push action
-uap deploy queue --agent-id my-agent --action-type push --target main --remote origin --force
-
-# Queue a merge action
-uap deploy queue --agent-id my-agent --action-type merge --target main
-
-# Queue a workflow trigger
-uap deploy queue --agent-id my-agent --action-type workflow --target CI --ref main --inputs '{"deploy_env":"production"}'
-```
-
-### Create and Execute Batches
-
-```bash
-# Create a batch from pending actions
-uap deploy batch
-
-# Execute a specific batch
-uap deploy execute --batch-id <batch-id>
-
-# Execute all pending batches
-uap deploy flush
-```
-
-### Check Status
-
-```bash
-# View queue status
-uap deploy status
-
-# View detailed status
-uap deploy status --verbose
-```
-
-## Configuration Schema
-
-The batch window configuration follows this schema:
-
-```typescript
-interface DynamicBatchWindows {
-  commit: number; // Default: 30000ms (30s)
-  push: number; // Default: 5000ms (5s)
-  merge: number; // Default: 10000ms (10s)
-  workflow: number; // Default: 5000ms (5s)
-  deploy: number; // Default: 60000ms (60s)
-}
-```
-
-## Best Practices
-
-### When to Adjust Windows
-
-1. **Increase windows** when:
-   - You want more aggressive batching
-   - Multiple developers are working on the same branch
-   - You prefer fewer, larger deployments
-
-2. **Decrease windows** when:
-   - You need faster feedback
-   - Time-sensitive deployments
-   - CI/CD pipeline is the bottleneck
-
-3. **Use urgent mode** when:
-   - Hotfix deployment
-   - Security patch
-   - Critical bug fix
-
-### Performance Considerations
-
-- **Shorter windows** = Faster execution but more individual operations
-- **Longer windows** = More batching but slower response time
-- **Parallel execution** works best for independent workflow triggers
-
-## Architecture
-
-The deploy system consists of:
-
-1. **DeployBatcher** - Core batching logic with dynamic windows
-2. **CoordinationService** - Manages agent coordination state
-3. **SQLite Database** - Persistent storage for pending actions and batches
-
-## API Reference
-
-### DeployBatcher Configuration
-
-```typescript
-interface DeployBatcherConfig {
-  dbPath?: string;
-  batchWindowMs?: number; // Legacy: single window for all types
-  dynamicWindows?: Partial<DynamicBatchWindows>; // NEW: per-type windows
-  maxBatchSize?: number;
-  dryRun?: boolean;
-  parallelExecution?: boolean;
-  maxParallelActions?: number;
-}
-```
-
-### Methods
-
-```typescript
-class DeployBatcher {
-  // Queue an action with type-specific batching
-  async queue(
-    agentId: string,
-    actionType: DeployActionType,
-    target: string,
-    payload?: Record<string, unknown>,
-    options?: { priority?: number; dependencies?: string[]; urgent?: boolean }
-  ): Promise<number>;
-
-  // Get current batch window for action type
-  getBatchWindow(actionType: DeployActionType): number;
-
-  // Set urgent mode
-  setUrgentMode(urgent: boolean): void;
-
-  // Get current configuration
-  getWindowConfig(): DynamicBatchWindows;
-
-  // Create batch from ready actions
-  async createBatch(): Promise<DeployBatch | null>;
-
-  // Execute a batch
-  async executeBatch(batchId: string): Promise<BatchResult>;
-
-  // Flush all pending deploys
-  async flushAll(): Promise<BatchResult[]>;
-}
-```
-
-## Troubleshooting
-
-### Actions Not Batching
-
-**Issue:** Actions remain in "pending" status for too long.
-
-**Solution:** Check batch window configuration:
-
-```bash
-uap deploy config
-```
-
-Adjust windows if needed:
-
-```bash
-uap deploy set-config --message '{"commit":5000,"push":2000}'
-```
-
-### Urgent Mode Not Working
-
-**Issue:** Urgent mode doesn't reduce wait times.
-
-**Solution:** Ensure you're using the correct flags:
-
-```bash
-uap deploy urgent --on
-```
-
-### Parallel Execution Not Working
-
-**Issue:** Actions execute sequentially instead of in parallel.
-
-**Solution:** Check that actions are independent (different action types or targets).
-
-## Related Documentation
-
-- [Deploy Command Reference](./CLI_DEPLOY.md)
-- [Coordination System](./COORDINATION.md)
-- [Batch Execution Guide](./BATCH_EXECUTION.md)
-
-## Version History
-
-- **v4.3.0** - Added dynamic batch windows per action type
-- **v4.2.0** - Added urgent mode for fast execution
-- **v4.1.0** - Added parallel execution for independent actions
-- **v4.0.0** - Initial deploy batching system