@kadi.build/deploy-ability 0.0.4 → 0.0.5

package/docs/PIPELINE_BUILDER_DESIGN.md

@@ -0,0 +1,1149 @@
+# Pipeline Builder Pattern Design Proposal
+
+> **Status**: Draft Proposal
+> **Author**: Design discussion with Claude Code
+> **Date**: 2025-11-18
+> **Target**: deploy-ability v0.1.0
+
+---
+
+## Table of Contents
+
+1. [Executive Summary](#executive-summary)
+2. [Current Design & Problems](#current-design--problems)
+3. [Proposed Solution: Pipeline Builder](#proposed-solution-pipeline-builder)
+4. [API Design](#api-design)
+5. [Before/After Comparison](#beforeafter-comparison)
+6. [Implementation Plan](#implementation-plan)
+7. [Migration Strategy](#migration-strategy)
+8. [Benefits & Trade-offs](#benefits--trade-offs)
+
+---
+
+## Executive Summary
+
+**Problem**: The current deploy-ability API has excellent separation of concerns but poor discoverability and error-prone usage patterns. Users must manually orchestrate registry setup, profile transformation, and cleanup - leading to easy mistakes and confusing errors.
+
+**Solution**: Introduce a fluent Pipeline Builder API that makes deployment steps explicit, discoverable, and safe by default. The pipeline handles orchestration, lifecycle management, and automatic cleanup while preserving the underlying composable primitives.
+
+**Impact**:
+- **Users**: Simpler, safer API that's hard to misuse
+- **Library**: Backward compatible - builder is new, primitives remain unchanged
+- **Code Quality**: Reduced boilerplate, automatic resource cleanup, better error messages
+
+---
+
+## Current Design & Problems
+
+### How It Works Today
+
+The current design separates concerns across multiple layers:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ Layer 1: kadi-deploy (CLI Orchestration)                   │
+│                                                             │
+│ 1. Load profile from agent.json                            │
+│ 2. Call setupRegistryIfNeeded() → returns transformed      │
+│ 3. Call deployToAkash() with transformed profile           │
+│ 4. Remember to call cleanup() in finally block             │
+└─────────────────────────────────────────────────────────────┘
+                           ↓
+┌─────────────────────────────────────────────────────────────┐
+│ Layer 2: deploy-ability (Library Primitives)               │
+│                                                             │
+│ • setupRegistryIfNeeded() - Optional pre-processing        │
+│ • deployToAkash() - Core deployment logic                  │
+│ • loadProfile() - Profile loading                          │
+│ • generateAkashSdl() - SDL generation                      │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Current Usage Pattern (kadi-deploy)
+
+```typescript
+// File: kadi-deploy/src/targets/akash/akash.ts
+
+export async function deployToAkash(ctx: DeploymentContext) {
+  const { profile, wallet, certificate, logger } = ctx;
+
+  // Step 1: Manually setup registry (easy to forget!)
+  const registryCtx = await setupRegistryIfNeeded(
+    profile,
+    logger,
+    {
+      containerEngine: 'docker',
+      tunnelService: 'serveo'
+    }
+  );
+
+  // Step 2: Remember the cleanup function for later
+  const cleanup = registryCtx.cleanup;
+
+  try {
+    // Step 3: Call deployment with transformed profile
+    const result = await deployToAkash({
+      loadedProfile: {
+        profile: registryCtx.deployableProfile  // ← Transformed!
+      },
+      wallet,
+      certificate,
+      bidSelector: selectCheapestBid,
+      logger
+    });
+
+    if (!result.success) {
+      throw new Error(result.error.message);
+    }
+
+    return result.data;
+
+  } finally {
+    // Step 4: Manual cleanup (easy to forget or get wrong!)
+    await cleanup();
+  }
+}
+```
+
+### Problems with Current Design
+
+#### 1. **Discoverability Problem**
+
+Looking at `deployToAkash()` signature, there's NO indication that local images require special handling:
+
+```typescript
+// What the signature shows:
+export async function deployToAkash(
+  params: AkashDeploymentExecution
+): Promise<AkashDeploymentResult>
+
+// What it DOESN'T show:
+// ⚠️  If your profile uses local images, call setupRegistryIfNeeded() first!
+// ⚠️  Don't forget to call the cleanup function!
+// ⚠️  Use a try-finally block to ensure cleanup happens!
+```
+
+**Result**: New users (or even experienced ones in a hurry) will write:
+
+```typescript
+// This looks right but FAILS at runtime! ❌
+const result = await deployToAkash({
+  projectRoot: './',
+  profile: 'my-profile',  // Contains "image": "my-app:latest"
+  wallet,
+  certificate,
+  bidSelector: selectCheapestBid
+});
+
+// Error (on Akash provider, minutes later):
+// "Failed to pull image: my-app:latest - not found"
+```
+
+The error happens **remotely** on the Akash provider, not locally where you can catch it early.
+
+#### 2. **Manual Lifecycle Management**
+
+Users must remember to:
+- Call `setupRegistryIfNeeded()` before deployment
+- Store the `cleanup` function
+- Call `cleanup()` in a finally block
+- Handle cleanup errors gracefully
+
+**This is error-prone**:
+
+```typescript
+// What if deployment throws before cleanup is set up?
+const registryCtx = await setupRegistryIfNeeded(...);
+const cleanup = registryCtx.cleanup;  // ← Not in try block yet!
+
+// What if user forgets finally block?
+try {
+  await deployToAkash(...);
+} catch (error) {
+  console.error(error);
+  return;  // ← Forgot cleanup! Registry keeps running!
+}
+
+// What if cleanup throws?
+finally {
+  await cleanup();  // ← Could throw and mask deployment errors
+}
+```
+
+#### 3. **Split Brain Problem**
+
+To understand the complete deployment flow, you need to know about:
+- **deploy-ability**: The core primitives (`deployToAkash`, `setupRegistryIfNeeded`)
+- **kadi-deploy**: The orchestration logic (how primitives are combined)
+
+There's no single place that shows the "canonical way" to deploy with local images.
+
+#### 4. **TypeScript Can't Help**
+
+The type system doesn't encode the relationship between local images and registry setup:
+
+```typescript
+// TypeScript is happy with this, but it's wrong at runtime:
+const profile: AkashDeploymentProfile = {
+  target: 'akash',
+  services: {
+    app: {
+      image: 'my-local-image:latest'  // ← Local image!
+    }
+  }
+};
+
+// TypeScript doesn't warn you about this:
+await deployToAkash({
+  loadedProfile: { profile },  // ← Missing registry setup!
+  wallet,
+  certificate
+});
+```
+
+#### 5. **Verbose Boilerplate**
+
+Every consumer of deploy-ability needs to write the same orchestration logic:
+
+```typescript
+// This pattern repeats in every deployment tool:
+const registryCtx = await setupRegistryIfNeeded(...);
+try {
+  const result = await deployToAkash({
+    loadedProfile: { profile: registryCtx.deployableProfile },
+    ...
+  });
+  return result;
+} finally {
+  await registryCtx.cleanup();
+}
+```
+
+---
+
+## Proposed Solution: Pipeline Builder
+
+### Core Concept
+
+Introduce a **fluent builder API** that:
+1. Makes deployment steps **explicit** and **discoverable**
+2. Handles **lifecycle management** automatically
+3. Provides **clear error messages** for missing steps
+4. Remains **backward compatible** (keeps existing primitives)
+
+### Mental Model
+
+Think of deployment as building a pipeline with stages:
+
+```
+Profile Loading → Registry Setup → Wallet → Certificate → Execution → Cleanup
+    (Stage 1)       (Stage 2)     (Stage 3)  (Stage 4)   (Stage 5)   (Auto)
+```
+
+Each stage:
+- Is **explicit** (you call a method to add it)
+- Is **validated** (builder checks you didn't skip required steps)
+- Is **typed** (TypeScript guides you through the steps)
+- Is **automatic** (lifecycle handled for you)
+
+### Key Design Principles
+
+1. **Fluent & Discoverable**: Chaining methods makes steps obvious
+2. **Safe by Default**: Can't execute without required stages
+3. **Automatic Cleanup**: Resources freed via RAII pattern
+4. **Backward Compatible**: Original functions still work
+5. **Progressive Disclosure**: Simple by default, powerful when needed
+
+---
+
+## API Design
+
+### Basic Usage
+
+```typescript
+import { DeploymentPipeline } from '@kadi.build/deploy-ability/akash';
+
+// Simple deployment with local images
+const result = await DeploymentPipeline
+  .create({ projectRoot: './', profile: 'production' })
+  .withLocalImageSupport({ tunnelService: 'serveo' })
+  .withWallet(wallet)
+  .withCertificate(certificate)
+  .execute();
+
+// Cleanup happens automatically!
+```
+
+### Advanced Usage
+
+```typescript
+// Full control with custom bid selection
+const result = await DeploymentPipeline
+  .create({
+    projectRoot: './',
+    profile: 'production',
+    network: 'mainnet'
+  })
+  .withLocalImageSupport({
+    tunnelService: 'ngrok',
+    tunnelAuthToken: process.env.NGROK_TOKEN
+  })
+  .withWallet(wallet)
+  .withCertificate(certificate)
+  .withBidSelector((bids) => {
+    const filtered = filterBids(bids, {
+      maxPricePerMonth: { usd: 50, aktPrice: 0.45 },
+      minUptime: { value: 0.95, period: '7d' }
+    });
+    return selectCheapestBid(filtered);
+  })
+  .withLogger(customLogger)
+  .execute();
+```
+
+### Conditional Registry Setup
+
+```typescript
+// Automatic detection - registry only starts if needed
+const result = await DeploymentPipeline
+  .create({ projectRoot: './', profile: 'production' })
+  .withLocalImageSupport()  // ← Auto-detects, no-op if all remote
+  .withWallet(wallet)
+  .withCertificate(certificate)
+  .execute();
+```
+
+### Pre-loaded Profile (Advanced)
+
+```typescript
+// When you already have a transformed profile
+const result = await DeploymentPipeline
+  .createFromProfile(transformedProfile, 'production')
+  .withWallet(wallet)
+  .withCertificate(certificate)
+  .execute();
+```
+
+### Dry Run Mode
+
+```typescript
+// Generate SDL without deploying
+const result = await DeploymentPipeline
+  .create({ projectRoot: './', profile: 'production' })
+  .dryRun();
+
+console.log('SDL:', result.data.sdl);
+```
+
+### Error Handling
+
+```typescript
+try {
+  const result = await DeploymentPipeline
+    .create({ projectRoot: './', profile: 'production' })
+    .withWallet(wallet)
+    .execute();  // ← Missing certificate!
+
+} catch (error) {
+  if (error instanceof PipelineValidationError) {
+    console.error('Pipeline not configured correctly:', error.message);
+    // "Certificate is required. Call .withCertificate() before .execute()"
+  }
+}
+```
+
+### Monitoring & Callbacks
+
+```typescript
+const result = await DeploymentPipeline
+  .create({ projectRoot: './', profile: 'production' })
+  .withLocalImageSupport()
+  .withWallet(wallet)
+  .withCertificate(certificate)
+  .onRegistryStarted((info) => {
+    console.log(`Registry available at: ${info.tunnelUrl}`);
+  })
+  .onBidsReceived((bids) => {
+    console.log(`Received ${bids.length} bids`);
+  })
+  .onLeaseCreated((lease) => {
+    console.log(`Lease created with ${lease.provider}`);
+  })
+  .execute();
+```
+
+---
+
+## Before/After Comparison
+
+### Consumer: kadi-deploy CLI
+
+#### Before (Current Design)
+
+```typescript
+// File: kadi-deploy/src/targets/akash/akash.ts
+
+import {
+  deployToAkash,
+  setupRegistryIfNeeded,
+  selectCheapestBid
+} from '@kadi.build/deploy-ability/akash';
+
+export async function deployAkashProfile(ctx: DeploymentContext) {
+  const { profile, wallet, certificate, logger } = ctx;
+
+  // Manual orchestration
+  logger.log('Setting up registry for local images...');
+  const registryCtx = await setupRegistryIfNeeded(
+    profile,
+    logger,
+    {
+      containerEngine: 'docker',
+      tunnelService: 'serveo'
+    }
+  );
+
+  const cleanup = registryCtx.cleanup;
+
+  try {
+    logger.log('Deploying to Akash...');
+
+    const result = await deployToAkash({
+      loadedProfile: {
+        profile: registryCtx.deployableProfile
+      },
+      wallet,
+      certificate,
+      bidSelector: selectCheapestBid,
+      logger
+    });
+
+    if (!result.success) {
+      throw new Error(result.error.message);
+    }
+
+    logger.log('✅ Deployment successful!');
+    return result.data;
+
+  } catch (error) {
+    logger.error('❌ Deployment failed:', error);
+    throw error;
+
+  } finally {
+    logger.log('Cleaning up registry...');
+    try {
+      await cleanup();
+    } catch (cleanupError) {
+      logger.warn('Warning: Registry cleanup failed:', cleanupError);
+    }
+  }
+}
+```
+
+**Issues**:
+- 48 lines of boilerplate
+- Manual lifecycle management
+- Nested try-catch for cleanup errors
+- Easy to forget steps
+
+#### After (Pipeline Builder)
+
+```typescript
+// File: kadi-deploy/src/targets/akash/akash.ts
+
+import {
+  DeploymentPipeline,
+  selectCheapestBid
+} from '@kadi.build/deploy-ability/akash';
+
+export async function deployAkashProfile(ctx: DeploymentContext) {
+  const { profile, wallet, certificate, logger } = ctx;
+
+  // Pipeline handles orchestration
+  const result = await DeploymentPipeline
+    .createFromProfile(profile, ctx.profileName)
+    .withLocalImageSupport({ tunnelService: 'serveo' })
+    .withWallet(wallet)
+    .withCertificate(certificate)
+    .withBidSelector(selectCheapestBid)
+    .withLogger(logger)
+    .execute();
+
+  if (!result.success) {
+    throw new Error(result.error.message);
+  }
+
+  return result.data;
+}
+```
+
+**Improvements**:
+- 19 lines (60% reduction)
+- No manual lifecycle management
+- Automatic cleanup (even on errors)
+- Clear, readable flow
+
+### Consumer: Custom Deployment Script
+
+#### Before (Current Design)
+
+```typescript
+// deploy.ts - User's custom deployment script
+
+import {
+  deployToAkash,
+  setupRegistryIfNeeded,
+  connectWallet,
+  ensureCertificate,
+  createSigningClient,
+  selectCheapestBid
+} from '@kadi.build/deploy-ability/akash';
+
+async function deploy() {
+  // Step 1: Connect wallet
+  const walletResult = await connectWallet({ network: 'mainnet' });
+  if (!walletResult.success) throw walletResult.error;
+
+  // Step 2: Ensure certificate
+  const clientResult = await createSigningClient(walletResult.data, 'mainnet');
+  if (!clientResult.success) throw clientResult.error;
+
+  const certResult = await ensureCertificate(
+    walletResult.data,
+    'mainnet',
+    clientResult.data.client
+  );
+  if (!certResult.success) throw certResult.error;
+
+  // Step 3: Load profile from disk
+  const profile = JSON.parse(
+    fs.readFileSync('./agent.json', 'utf-8')
+  ).deploy['production'];
+
+  // Step 4: Setup registry
+  const registryCtx = await setupRegistryIfNeeded(profile, console, {
+    containerEngine: 'docker',
+    tunnelService: 'serveo'
+  });
+
+  try {
+    // Step 5: Deploy
+    const result = await deployToAkash({
+      loadedProfile: { profile: registryCtx.deployableProfile },
+      wallet: walletResult.data,
+      certificate: certResult.data,
+      bidSelector: selectCheapestBid
+    });
+
+    if (!result.success) {
+      throw new Error(result.error.message);
+    }
+
+    console.log('Deployed!', result.data);
+
+  } finally {
+    await registryCtx.cleanup();
+  }
+}
+
+deploy().catch(console.error);
+```
+
+**Issues**:
+- Verbose error checking
+- Manual orchestration
+- Easy to forget cleanup
+
+#### After (Pipeline Builder)
+
+```typescript
+// deploy.ts - User's custom deployment script
+
+import {
+  DeploymentPipeline,
+  connectWallet,
+  ensureCertificate,
+  createSigningClient,
+  selectCheapestBid
+} from '@kadi.build/deploy-ability/akash';
+
+async function deploy() {
+  // Setup wallet & certificate (same as before)
+  const walletResult = await connectWallet({ network: 'mainnet' });
+  if (!walletResult.success) throw walletResult.error;
+
+  const clientResult = await createSigningClient(walletResult.data, 'mainnet');
+  if (!clientResult.success) throw clientResult.error;
+
+  const certResult = await ensureCertificate(
+    walletResult.data,
+    'mainnet',
+    clientResult.data.client
+  );
+  if (!certResult.success) throw certResult.error;
+
+  // Deploy with pipeline - much simpler!
+  const result = await DeploymentPipeline
+    .create({
+      projectRoot: './',
+      profile: 'production',
+      network: 'mainnet'
+    })
+    .withLocalImageSupport({ tunnelService: 'serveo' })
+    .withWallet(walletResult.data)
+    .withCertificate(certResult.data)
+    .withBidSelector(selectCheapestBid)
+    .execute();
+
+  if (!result.success) {
+    throw new Error(result.error.message);
+  }
+
+  console.log('Deployed!', result.data);
+}
+
+deploy().catch(console.error);
+```
+
+**Improvements**:
+- Cleaner deployment orchestration
+- No manual cleanup
+- Easier to read and understand
+
+### Consumer: Autonomous Agent (Model Manager)
+
+#### Before (Current Design)
+
+```typescript
+// src/services/deployment-logic.ts (Model Manager Agent)
+
+async deployModel(request: DeploymentRequest) {
+  const profile = this.profileGenerator.generate(request);
+
+  // Manual registry setup
+  const registryCtx = await setupRegistryIfNeeded(
+    profile,
+    this.logger,
+    { containerEngine: 'docker' }
+  );
+
+  try {
+    const result = await deployToAkash({
+      loadedProfile: { profile: registryCtx.deployableProfile },
+      wallet: this.walletContext,
+      certificate: this.certificate,
+      bidSelector: selectCheapestBid,
+      logger: this.logger
+    });
+
+    if (!result.success) {
+      throw new Error(result.error.message);
+    }
+
+    return {
+      dseq: result.data.dseq,
+      provider: result.data.providerUri,
+      endpoints: result.data.endpoints
+    };
+
+  } finally {
+    await registryCtx.cleanup();
+  }
+}
+```
+
+#### After (Pipeline Builder)
+
+```typescript
+// src/services/deployment-logic.ts (Model Manager Agent)
+
+async deployModel(request: DeploymentRequest) {
+  const profile = this.profileGenerator.generate(request);
+
+  // Pipeline handles everything
+  const result = await DeploymentPipeline
+    .createFromProfile(profile, request.model.name)
+    .withLocalImageSupport()  // Auto-detects, no-op if not needed
+    .withWallet(this.walletContext)
+    .withCertificate(this.certificate)
+    .withBidSelector(selectCheapestBid)
+    .withLogger(this.logger)
+    .execute();
+
+  if (!result.success) {
+    throw new Error(result.error.message);
+  }
+
+  return {
+    dseq: result.data.dseq,
+    provider: result.data.providerUri,
+    endpoints: result.data.endpoints
+  };
+}
+```
+
+**Improvements**:
+- Simpler agent code
+- Automatic resource cleanup
+- Better error handling
+
+---
+
+## Implementation Plan
+
+### Phase 1: Core Pipeline Builder
+
+**Goal**: Implement basic pipeline with existing primitives
+
+**Files to Create**:
+```
+src/targets/akash/
+  ├── pipeline/
+  │   ├── index.ts              # Public exports
+  │   ├── DeploymentPipeline.ts # Main builder class
+  │   ├── PipelineStage.ts      # Stage definitions
+  │   ├── PipelineContext.ts    # Internal state
+  │   ├── PipelineValidator.ts  # Validation logic
+  │   └── errors.ts             # Pipeline-specific errors
+```
+
+**Implementation**:
+
+```typescript
+// src/targets/akash/pipeline/DeploymentPipeline.ts
+
+export class DeploymentPipeline {
+  private context: PipelineContext;
+
+  private constructor(context: PipelineContext) {
+    this.context = context;
+  }
+
+  // ========================================
+  // Factory Methods
+  // ========================================
+
+  static create(options: {
+    projectRoot: string;
+    profile: string;
+    network?: AkashNetwork;
+  }): DeploymentPipeline {
+    return new DeploymentPipeline({
+      stage: 'initialized',
+      options
+    });
+  }
+
+  static createFromProfile(
+    profile: AkashDeploymentProfile,
+    profileName: string
+  ): DeploymentPipeline {
+    return new DeploymentPipeline({
+      stage: 'profile-loaded',
+      loadedProfile: { profile, name: profileName }
+    });
+  }
+
+  // ========================================
+  // Builder Methods
+  // ========================================
+
+  withLocalImageSupport(options?: RegistryOptions): DeploymentPipeline {
+    this.context.registryOptions = options || {};
+    this.context.enableRegistry = true;
+    return this;
+  }
+
+  withWallet(wallet: WalletContext): DeploymentPipeline {
+    this.context.wallet = wallet;
+    return this;
+  }
+
+  withCertificate(certificate: AkashProviderTlsCertificate): DeploymentPipeline {
+    this.context.certificate = certificate;
+    return this;
+  }
+
+  withBidSelector(selector: BidSelector): DeploymentPipeline {
+    this.context.bidSelector = selector;
+    return this;
+  }
+
+  withLogger(logger: DeploymentLogger): DeploymentPipeline {
+    this.context.logger = logger;
+    return this;
+  }
+
+  // ========================================
+  // Execution
+  // ========================================
+
+  async execute(): Promise<AkashDeploymentResult> {
+    // Validate pipeline configuration
+    this.validate();
+
+    // Track resources for cleanup
+    const resources: ResourceHandle[] = [];
+
+    try {
+      // Stage 1: Load profile if needed
+      await this.loadProfileIfNeeded();
+
+      // Stage 2: Setup registry if needed
+      const registryHandle = await this.setupRegistryIfNeeded();
+      if (registryHandle) resources.push(registryHandle);
+
+      // Stage 3: Deploy to Akash
+      const result = await this.deploy();
+
+      return result;
+
+    } finally {
+      // Automatic cleanup (reverse order)
+      await this.cleanup(resources);
+    }
+  }
+
+  async dryRun(): Promise<AkashDeploymentResult> {
+    await this.loadProfileIfNeeded();
+    // Generate SDL only, no deployment
+    const sdl = generateAkashSdl(this.context.loadedProfile!);
+    return success({
+      dryRun: true,
+      sdl,
+      profile: this.context.loadedProfile!.name,
+      network: this.context.options!.network || 'mainnet'
+    });
+  }
+
+  // ========================================
+  // Internal Methods
+  // ========================================
+
+  private validate(): void {
+    if (!this.context.wallet) {
+      throw new PipelineValidationError(
+        'Wallet is required. Call .withWallet(wallet) before .execute()'
+      );
+    }
+
+    if (!this.context.certificate) {
+      throw new PipelineValidationError(
+        'Certificate is required. Call .withCertificate(cert) before .execute()'
+      );
+    }
+
+    // More validation...
+  }
+
+  private async loadProfileIfNeeded(): Promise<void> {
+    if (this.context.loadedProfile) return;
+
+    const profile = await loadProfile(
+      this.context.options!.projectRoot,
+      this.context.options!.profile,
+      this.context.logger || defaultLogger
+    );
+
+    this.context.loadedProfile = profile;
+  }
+
+  private async setupRegistryIfNeeded(): Promise<ResourceHandle | null> {
+    if (!this.context.enableRegistry) return null;
+
+    const logger = this.context.logger || defaultLogger;
+    const registryCtx = await setupRegistryIfNeeded(
+      this.context.loadedProfile!.profile,
+      logger,
+      this.context.registryOptions
+    );
+
+    // Update profile with transformed version
+    this.context.loadedProfile!.profile = registryCtx.deployableProfile;
+
+    // Return cleanup handle
+    return {
+      name: 'registry',
+      cleanup: registryCtx.cleanup
+    };
+  }
+
+  private async deploy(): Promise<AkashDeploymentResult> {
+    return deployToAkash({
+      loadedProfile: this.context.loadedProfile!,
+      wallet: this.context.wallet!,
+      certificate: this.context.certificate!,
+      bidSelector: this.context.bidSelector || selectCheapestBid,
+      logger: this.context.logger
+    });
+  }
+
+  private async cleanup(resources: ResourceHandle[]): Promise<void> {
+    // Cleanup in reverse order (LIFO)
+    for (const resource of resources.reverse()) {
+      try {
+        await resource.cleanup();
+      } catch (error) {
+        const logger = this.context.logger || defaultLogger;
+        logger.warn(`Failed to cleanup ${resource.name}:`, error);
+      }
+    }
+  }
+}
+
+// ========================================
+// Supporting Types
+// ========================================
+
+interface PipelineContext {
+  stage: 'initialized' | 'profile-loaded' | 'registry-setup' | 'deploying';
+  options?: {
+    projectRoot: string;
+    profile: string;
+    network?: AkashNetwork;
+  };
+  loadedProfile?: {
+    profile: AkashDeploymentProfile;
+    name: string;
+  };
+  enableRegistry?: boolean;
+  registryOptions?: RegistryOptions;
+  wallet?: WalletContext;
+  certificate?: AkashProviderTlsCertificate;
+  bidSelector?: BidSelector;
+  logger?: DeploymentLogger;
+}
+
+interface ResourceHandle {
+  name: string;
+  cleanup: () => Promise<void>;
+}
+
+export class PipelineValidationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'PipelineValidationError';
+  }
+}
+```
+
+### Phase 2: Enhanced Features
+
+**Add lifecycle callbacks**:
+
+```typescript
+withCallbacks(callbacks: {
+  onRegistryStarted?: (info: RegistryInfo) => void;
+  onProfileLoaded?: (profile: AkashDeploymentProfile) => void;
+  onBidsReceived?: (bids: EnhancedBid[]) => void;
+  onLeaseCreated?: (lease: LeaseDetails) => void;
+}): DeploymentPipeline
+```
+
+**Add monitoring integration**:
+
+```typescript
+withMonitoring(options: {
+  waitForContainers?: boolean;
+  containerTimeout?: number;
+  streamLogs?: boolean;
+}): DeploymentPipeline
+```
+
+### Phase 3: Documentation & Examples
+
+1. Update main README with pipeline examples
+2. Create `docs/PIPELINE_API.md` with full API reference
+3. Add examples to `examples/` directory
+4. Update TypeDoc comments
+
+---
+
+## Migration Strategy
+
+### Backward Compatibility
+
+**Principle**: The pipeline builder is **additive** - all existing functions remain unchanged.
+
+```typescript
+// Old way still works!
+import { deployToAkash, setupRegistryIfNeeded } from '@kadi.build/deploy-ability/akash';
+
+const registryCtx = await setupRegistryIfNeeded(...);
+try {
+  const result = await deployToAkash({
+    loadedProfile: { profile: registryCtx.deployableProfile },
+    ...
+  });
+} finally {
+  await registryCtx.cleanup();
+}
+```
+
+```typescript
+// New way is optional
+import { DeploymentPipeline } from '@kadi.build/deploy-ability/akash';
+
+const result = await DeploymentPipeline
+  .create({ projectRoot: './', profile: 'prod' })
+  .withLocalImageSupport()
+  .withWallet(wallet)
+  .withCertificate(cert)
+  .execute();
+```
+
+### Migration Path
+
+#### Step 1: Soft Deprecation (v0.1.0)
+
+- Add pipeline builder to library
+- Update docs to show pipeline as recommended approach
+- Mark old approach as "still supported"
+
+```typescript
+/**
+ * @deprecated Prefer using DeploymentPipeline for better ergonomics
+ * @see DeploymentPipeline
+ */
+export async function deployToAkash(...) { ... }
+```
+
+#### Step 2: Community Feedback (v0.2.0 - v0.5.0)
+
+- Gather feedback on pipeline API
+- Iterate on design based on real usage
+- Keep both approaches working
+
+#### Step 3: Hard Deprecation (v1.0.0)
+
+- Pipeline is primary API
+- Old functions remain but warn in console
+- Documentation shows pipeline only
+
+#### Step 4: Removal (v2.0.0)
+
+- Remove old functions (breaking change)
+- Pipeline is the only way
+
+### Gradual Adoption
+
+**Users can adopt incrementally**:
+
+```typescript
+// Week 1: Just wrap existing code
+const result = await DeploymentPipeline
+  .createFromProfile(profile, 'prod')
+  .withWallet(wallet)
+  .withCertificate(cert)
+  .execute();
+
+// Week 2: Add local image support
+const result = await DeploymentPipeline
+  .create({ projectRoot: './', profile: 'prod' })
+  .withLocalImageSupport()  // ← New!
+  .withWallet(wallet)
+  .withCertificate(cert)
+  .execute();
+
+// Week 3: Add custom bid selection
+const result = await DeploymentPipeline
+  .create({ projectRoot: './', profile: 'prod' })
+  .withLocalImageSupport()
+  .withWallet(wallet)
+  .withCertificate(cert)
+  .withBidSelector(customSelector)  // ← New!
+  .execute();
+```
+
+---
+
+## Benefits & Trade-offs
+
+### Benefits
+
+#### 1. **Discoverability**
+- IDE autocomplete guides you through steps
+- Method names are self-documenting
+- Can't forget required steps
+
+#### 2. **Safety**
+- Validation catches configuration errors early
+- Automatic cleanup prevents resource leaks
+- Type system encodes requirements
+
+#### 3. **Ergonomics**
+- Less boilerplate (60% reduction)
+- No manual lifecycle management
+- Cleaner, more readable code
+
+#### 4. **Flexibility**
+- Stages are optional (progressive disclosure)
+- Can still use primitives for advanced cases
+- Backward compatible
+
+#### 5. **Error Messages**
+```typescript
+// Before: Confusing error at runtime on Akash
+"Failed to pull image: my-app:latest"
+
+// After: Clear error immediately
+"Pipeline validation failed: Wallet is required.
+Call .withWallet(wallet) before .execute()"
+```
+
+### Trade-offs
+
+#### 1. **More Code in Library**
+- **Cost**: ~500 lines for pipeline implementation
+- **Benefit**: Shared across all consumers (net reduction overall)
+
+#### 2. **Learning Curve**
+- **Cost**: Users need to learn builder pattern
+- **Benefit**: Pattern is familiar from other libraries (e.g., Axios, TypeORM)
+
+#### 3. **Less Control**
+- **Cost**: Some orchestration is hidden
+- **Benefit**: Can still use primitives for full control
+
+#### 4. **Testing Complexity**
+- **Cost**: Need to test pipeline stages
+- **Benefit**: Better test coverage overall
+
+### Comparison Table
+
+| Aspect | Current (Primitives) | Pipeline Builder |
+|--------|---------------------|------------------|
+| **Lines of Code** | ~40-50 lines | ~15-20 lines |
+| **Discoverability** | ❌ Poor | ✅ Excellent |
+| **Error Messages** | ❌ Confusing | ✅ Clear |
+| **Lifecycle Management** | ❌ Manual | ✅ Automatic |
+| **Type Safety** | ⚠️  Partial | ✅ Complete |
+| **Flexibility** | ✅ Full control | ✅ Still available |
+| **Learning Curve** | ⚠️  Medium | ⚠️  Medium |
+| **Code in Library** | ✅ Minimal | ⚠️  More |
+
+---
+
+## Conclusion
+
+The Pipeline Builder pattern addresses the key usability issues with deploy-ability while maintaining its architectural strengths. By making deployment steps explicit and handling lifecycle automatically, we create an API that's both powerful and hard to misuse.
+
+### Next Steps
+
+1. **Review**: Gather feedback on this proposal
+2. **Prototype**: Implement Phase 1 (core pipeline)
+3. **Test**: Migrate kadi-deploy to use pipeline
+4. **Iterate**: Refine based on real usage
+5. **Document**: Write comprehensive guides
+6. **Release**: Ship as part of deploy-ability v0.1.0
+
+### Open Questions
+
+1. Should pipeline builder be in a separate package or same as deploy-ability?
+2. What's the right balance between automatic and explicit?
+3. Should we support middleware/plugins for custom stages?
+4. How should we handle errors in pipeline stages?
+
+---
+
+**Feedback Welcome**: Please share thoughts, concerns, or suggestions!