CiderFlight™ v2.0.0 Quickstart & Integration Guide

Scope: Stage 1 type-check + 200 ms @ViewBuilder gate + optional Stage 2 headless checks. Built for AI coding agents and Linux CI. Complements (does not replace) Xcode or on-device testing.

MCP methods

• verify_ios_swift — Stage 1 type-check plus the 200 ms @ViewBuilder expression-complexity gate; returns line- and column-exact JSON diagnostics.
• inspect_viewbuilder_complexity — reports @ViewBuilder expressions over the 200 ms threshold, with remediation hints.
• snapshot_headless_layout — Stage 2 structural layout and accessibility snapshot (viewport overflow, tap-target minimums, missing labels).

Stage 1 vs. Stage 2

• Stage 1 (always on): Linux swiftc -typecheck against the 17-framework shim plus the 200 ms @ViewBuilder gate. No code is executed.
• Stage 2 (optional, --run-headless): runs only after Stage 1 passes; links a sandboxed Linux x86_64 ELF and executes headless assertions on state transitions, in-memory data models, PDF output, and the structural layout/accessibility tree. No pixel rendering.

2. Two-Stage Technical Architecture & Scope Boundaries

CiderFlight executes a deterministic two-stage compile and headless behavioral verification pipeline on standard x86_64 Linux hosts without requiring a macOS virtual machine during the inner agent loop:

Deterministic JSON Output Schema

Both the CLI (ciderflight <File.swift> --run-headless --json) and MCP tools (verify_ios_swift, inspect_viewbuilder_complexity, snapshot_headless_layout) return a deterministic JSON payload:

{
  "status": "passed | failed",
  "stage": "stage1_typecheck | stage2_headless_elf",
  "stage1_typecheck_ms": 176.4,
  "stage2_exec_ms": 512.8,
  "elapsed_ms": 689.2,
  "delta_line_invariant": 0,
  "sdk_cache": { "cache_hit": true, "frameworks_loaded": 17 },
  "diagnostics": [
    {
      "file": "live_demo/CoffeeOrderBroken.swift",
      "line": 16,
      "column": 39,
      "severity": "error",
      "category": "type_mismatch",
      "message": "cannot convert value of type 'String' to specified type 'Bool'"
    }
  ],
  "slow_expressions": [
    {
      "file": "live_demo/CoffeeOrderBroken.swift",
      "line": 35,
      "column": 24,
      "estimated_ms": 340,
      "threshold_ms": 200,
      "category": "viewbuilder_complexity_gate",
      "remediation": "Extract chained arithmetic into an explicitly typed local let binding or helper @ViewBuilder subview."
    }
  ],
  "headless_runtime": {
    "exit_code": 0,
    "assertions_passed": 4,
    "layout_snapshot": { "root": "NavigationStack", "overflows_viewport": false, "small_tap_targets": 0 }
  }
}

Explicit Supported Surface & Known Limitations

100% Clean-Room Provenance: CiderFlight is authored from the ground up on Linux against publicly documented API signatures and open-source Swift 6.0 toolchains, with zero Apple proprietary SDK headers, zero Xcode binaries, and zero decompiled Darwin libraries. See Legal, Clean-Room Provenance & Patent Notice.

3. Benchmarks, Reproducible Methodology & Inspectable Fixture

All timings below are measured compiler and headless-runtime wall-clock telemetry on an x86_64 Linux container (Ubuntu 24.04 LTS, open-source Swift 6.0.3 Linux toolchain, warm flock-synchronized CiderFlightSDK.swiftmodule cache). Agent retry-turn and token-consumption deltas depend on the host model and prompt harness and are measured jointly during a 90-Day Platform Pilot.

Inspectable & Copy-Pasteable Reproduction Fixtures

Run these commands inside any evaluation container to reproduce Stage 1 diagnostic accuracy (Delta_line == 0), the 200 ms @ViewBuilder gate, and Stage 2 headless ELF execution:

# 1. Verify binary tarball integrity (SHA-256):
echo "265fea2a3602495f04b1243e9de49a3b89d0d03ec87bceb9ef8e60553273db46  ciderflight-linux-x86_64-binary.tar.gz" | sha256sum -c -

# 2. Stage 1 diagnostic catch (Line 16 Col 39 type mismatch + Line 35 @ViewBuilder gate):
ciderflight live_demo/CoffeeOrderBroken.swift --json

# 3. Stage 1 + Stage 2 headless ELF execution & %PDF-1.4 synthesis:
ciderflight live_demo/CoffeeOrderApp.swift --run-headless --json

# 4. Run the 5-app multi-framework benchmark suite (broad_market_ios_benchmarks.swift):
python3 benchmarks/run_5_app_suite.py --json

// --- live_demo/CoffeeOrderBroken.swift ---
import Foundation
#if os(iOS)
import SwiftUI
import UIKit
import Observation
import PDFKit
#endif

@Observable
public final class CoffeeCartModel {
    public var customerName: String = "William"
    public var selectedDrink: String = "Double Cortado"
    public var shotCount: Int = 2
    public var basePrice: Double = 4.50
    public var extraShotPrice: Double = 0.75
    public var isOrderPlaced: Bool =  "BROKEN_TYPE_AT_LINE_16_COL_39"
    public var receiptID: String = ""
    public init() {}
}

public struct CoffeeOrderBrokenView: View {
    @State private var a: Double = 1.0
    @State private var b: Double = 2.0
    @State private var c: Double = 3.0
    @State private var d: Double = 4.0

    public var body: some View {
        VStack(spacing: CGFloat((a + b + c + d) * (a - b + c - d) + (a * b - c * d) + (a / b + c / d) + (a + b * c - d / a) + (b * c + d * a - a * c))) {
            Text("Broken & Pathological ViewBuilder")
        }
    }
}

4. 1-Line CLI Installation, Host Requirements & SHA-256 Verification

Install the SHA-256-verified CiderFlight binary on Ubuntu 22.04/24.04, Debian, Windows (via WSL2), or any x86-64 Linux container with Python 3.10–3.13. The download service is launching soon; until it is live, request access at licensing@ciderflight.com.

# 1. Set your Pro ($12/mo), Student .edu ($6/mo), or Team ($19/user/mo) license key
#    (required: the binary is served only via authenticated GET /v1/releases/download):
export CIDERFLIGHT_LICENSE_KEY="cf_pro_your_license_key_here"

# 2. Install (fails with a clear error if the key is missing or invalid; verifies SHA-256):
curl -fsSL https://ciderflight.com/install.sh | bash

# Verify a Swift file or project directory:
~/.ciderflight/bin/ciderflight Sources/ --run-headless --json

5. Cursor, Claude Code & Windsurf MCP Setup

Add CiderFlight to your AI assistant's Model Context Protocol (MCP) configuration. Whenever your AI writes or edits a .swift file, it automatically invokes CiderFlight, reads the structured diagnostics, and fixes any bugs before handing the code back to you:

{
  "mcpServers": {
    "ciderflight": {
      "url": "https://api.ciderflight.dev/v1/mcp",
      "headers": {
        "Authorization": "Bearer cf_pro_your_license_key_here"
      }
    }
  }
}

Your ready-to-copy config (with your key filled in) is also shown in the Customer Portal after your key is verified.

6. GitHub Actions Linux CI Setup

Add CIDERFLIGHT_LICENSE_KEY to your repository's Settings → Secrets and variables → Actions, then run CiderFlight on fast, low-cost Linux runners on every pull request:

jobs:
  ciderflight-preflight:
    runs-on: ubuntu-latest
    env:
      CIDERFLIGHT_LICENSE_KEY: ${{ secrets.CIDERFLIGHT_LICENSE_KEY }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.10 - 3.13'
      # Requires an open-source Swift 6.0.x Linux toolchain installed on the runner.
      - name: Install CiderFlight (authenticated download + SHA-256 check)
        run: curl -fsSL https://ciderflight.com/install.sh | bash
      - name: Run CiderFlight verification
        run: ~/.ciderflight/bin/ciderflight Sources/ --run-headless --json

7. Supported iOS & SwiftUI Framework APIs (17 Frameworks)