Squashed 'vendor/ruvector/' content from commit b64c2172

git-subtree-dir: vendor/ruvector
git-subtree-split: b64c21726f2bb37286d9ee36a7869fef60cc6900

examples/app-clip/Sources/AppClip/AppClipApp.swift

@@ -0,0 +1,73 @@
+// AppClipApp.swift — Entry point for the RVF App Clip.
+//
+// This is a minimal SwiftUI App Clip that scans QR cognitive seeds
+// and decodes them using the RVF C FFI. Designed to stay under the
+// 15 MB App Clip size limit per Apple guidelines.
+//
+// App Clip invocation URL scheme:
+//   https://rvf.example.com/seed?id=<file_id>
+//
+// The App Clip can be invoked by:
+//   1. Scanning an RVQS QR code directly (camera flow)
+//   2. Tapping an App Clip Code / NFC tag
+//   3. Opening a Smart App Banner link
+
+import SwiftUI
+
+@main
+struct AppClipApp: App {
+    @StateObject private var appState = AppClipState()
+
+    var body: some Scene {
+        WindowGroup {
+            AppClipView()
+                .onContinueUserActivity(
+                    NSUserActivityTypeBrowsingWeb,
+                    perform: handleUserActivity
+                )
+                .environmentObject(appState)
+        }
+    }
+
+    /// Handle App Clip invocation via URL.
+    ///
+    /// When the App Clip is launched from a Smart App Banner or App Clip Code,
+    /// iOS delivers the invocation URL as a user activity. We extract the
+    /// seed identifier and trigger a download + decode flow.
+    private func handleUserActivity(_ activity: NSUserActivity) {
+        guard let url = activity.webpageURL else { return }
+        appState.handleInvocationURL(url)
+    }
+}
+
+// MARK: - AppClipState
+
+/// Shared state for App Clip lifecycle and invocation handling.
+@MainActor
+final class AppClipState: ObservableObject {
+
+    /// The invocation URL that launched this App Clip (if any).
+    @Published var invocationURL: URL?
+
+    /// Handle an App Clip invocation URL.
+    ///
+    /// Extracts the seed ID from the URL query parameters and could
+    /// trigger a network fetch for the seed payload.
+    func handleInvocationURL(_ url: URL) {
+        invocationURL = url
+
+        // Extract seed ID from query parameters.
+        // Example: https://rvf.example.com/seed?id=0102030405060708
+        guard let components = URLComponents(url: url, resolvingAgainstBaseURL: false),
+              let seedIDParam = components.queryItems?.first(where: { $0.name == "id" }),
+              let _ = seedIDParam.value
+        else {
+            return
+        }
+
+        // In production:
+        // 1. Fetch the seed payload from the CDN using the seed ID.
+        // 2. Pass the raw bytes to SeedDecoder.decode(data:).
+        // 3. Begin progressive download of the full RVF file.
+    }
+}

examples/app-clip/Sources/AppClip/AppClipView.swift

@@ -0,0 +1,338 @@
+// AppClipView.swift — SwiftUI view for the RVF App Clip.
+//
+// Presents a QR scanner interface and displays decoded seed information.
+// Uses AVFoundation for camera access and the SeedDecoder for parsing.
+
+import SwiftUI
+import AVFoundation
+
+// MARK: - AppClipView
+
+/// Root view for the App Clip experience.
+///
+/// Flow: Scan QR -> Decode RVQS seed -> Display cognitive seed info.
+struct AppClipView: View {
+    @StateObject private var viewModel = AppClipViewModel()
+
+    var body: some View {
+        NavigationStack {
+            VStack(spacing: 0) {
+                switch viewModel.state {
+                case .scanning:
+                    scannerSection
+                case .decoding:
+                    decodingSection
+                case .decoded(let info):
+                    decodedSection(info)
+                case .error(let message):
+                    errorSection(message)
+                }
+            }
+            .navigationTitle("RVF Seed Scanner")
+            .navigationBarTitleDisplayMode(.inline)
+        }
+    }
+
+    // MARK: - Scanner
+
+    private var scannerSection: some View {
+        VStack(spacing: 24) {
+            Spacer()
+
+            // Camera preview placeholder.
+            // In production, this would be a UIViewRepresentable wrapping
+            // an AVCaptureVideoPreviewLayer for real-time QR scanning.
+            ZStack {
+                RoundedRectangle(cornerRadius: 16)
+                    .fill(Color.black.opacity(0.8))
+                    .frame(width: 280, height: 280)
+
+                RoundedRectangle(cornerRadius: 12)
+                    .strokeBorder(Color.white.opacity(0.6), lineWidth: 2)
+                    .frame(width: 240, height: 240)
+
+                VStack(spacing: 12) {
+                    Image(systemName: "qrcode.viewfinder")
+                        .font(.system(size: 48))
+                        .foregroundStyle(.white)
+                    Text("Point camera at QR seed")
+                        .font(.subheadline)
+                        .foregroundStyle(.white.opacity(0.8))
+                }
+            }
+
+            Text("Scan a cognitive seed QR code to bootstrap intelligence.")
+                .font(.footnote)
+                .foregroundStyle(.secondary)
+                .multilineTextAlignment(.center)
+                .padding(.horizontal, 32)
+
+            // Demo button for testing without a camera.
+            Button {
+                viewModel.decodeDemoSeed()
+            } label: {
+                Label("Use Demo Seed", systemImage: "doc.viewfinder")
+                    .font(.body.weight(.medium))
+            }
+            .buttonStyle(.borderedProminent)
+            .tint(.blue)
+
+            Spacer()
+        }
+    }
+
+    // MARK: - Decoding
+
+    private var decodingSection: some View {
+        VStack(spacing: 16) {
+            Spacer()
+            ProgressView()
+                .scaleEffect(1.5)
+            Text("Decoding seed...")
+                .font(.headline)
+                .foregroundStyle(.secondary)
+            Spacer()
+        }
+    }
+
+    // MARK: - Decoded Result
+
+    private func decodedSection(_ info: SeedInfo) -> some View {
+        ScrollView {
+            VStack(alignment: .leading, spacing: 16) {
+                // Header card.
+                GroupBox {
+                    VStack(alignment: .leading, spacing: 8) {
+                        Label("Cognitive Seed", systemImage: "brain")
+                            .font(.headline)
+
+                        Divider()
+
+                        infoRow("Version", value: "v\(info.version)")
+                        infoRow("Dimension", value: "\(info.dimension)")
+                        infoRow("Vectors", value: formatCount(info.totalVectorCount))
+                        infoRow("Seed Size", value: formatBytes(info.totalSeedSize))
+                    }
+                }
+
+                // Content hash.
+                GroupBox {
+                    VStack(alignment: .leading, spacing: 8) {
+                        Label("Content Hash", systemImage: "number")
+                            .font(.headline)
+
+                        Divider()
+
+                        Text(info.contentHash)
+                            .font(.system(.caption, design: .monospaced))
+                            .foregroundStyle(.secondary)
+                            .textSelection(.enabled)
+                    }
+                }
+
+                // Manifest info.
+                GroupBox {
+                    VStack(alignment: .leading, spacing: 8) {
+                        Label("Manifest", systemImage: "arrow.down.circle")
+                            .font(.headline)
+
+                        Divider()
+
+                        infoRow("Hosts", value: "\(info.hosts)")
+                        infoRow("Layers", value: "\(info.layers)")
+                        infoRow("Microkernel", value: info.hasMicrokernel ? "Yes" : "No")
+                        infoRow("Signed", value: info.isSigned ? "Yes" : "No")
+
+                        if let url = info.primaryHostURL {
+                            VStack(alignment: .leading, spacing: 4) {
+                                Text("Primary Host")
+                                    .font(.caption)
+                                    .foregroundStyle(.secondary)
+                                Text(url)
+                                    .font(.system(.caption2, design: .monospaced))
+                                    .foregroundStyle(.blue)
+                                    .textSelection(.enabled)
+                            }
+                        }
+                    }
+                }
+
+                // Action buttons.
+                Button {
+                    viewModel.reset()
+                } label: {
+                    Label("Scan Another", systemImage: "qrcode.viewfinder")
+                        .frame(maxWidth: .infinity)
+                }
+                .buttonStyle(.borderedProminent)
+            }
+            .padding()
+        }
+    }
+
+    // MARK: - Error
+
+    private func errorSection(_ message: String) -> some View {
+        VStack(spacing: 24) {
+            Spacer()
+
+            Image(systemName: "exclamationmark.triangle.fill")
+                .font(.system(size: 48))
+                .foregroundStyle(.red)
+
+            Text("Decode Failed")
+                .font(.title2.weight(.semibold))
+
+            Text(message)
+                .font(.body)
+                .foregroundStyle(.secondary)
+                .multilineTextAlignment(.center)
+                .padding(.horizontal, 32)
+
+            Button {
+                viewModel.reset()
+            } label: {
+                Label("Try Again", systemImage: "arrow.counterclockwise")
+                    .font(.body.weight(.medium))
+            }
+            .buttonStyle(.borderedProminent)
+
+            Spacer()
+        }
+    }
+
+    // MARK: - Helpers
+
+    private func infoRow(_ label: String, value: String) -> some View {
+        HStack {
+            Text(label)
+                .font(.subheadline)
+                .foregroundStyle(.secondary)
+            Spacer()
+            Text(value)
+                .font(.subheadline.weight(.medium))
+        }
+    }
+
+    private func formatCount(_ count: UInt32) -> String {
+        if count >= 1_000_000 {
+            return String(format: "%.1fM", Double(count) / 1_000_000.0)
+        } else if count >= 1_000 {
+            return String(format: "%.1fK", Double(count) / 1_000.0)
+        }
+        return "\(count)"
+    }
+
+    private func formatBytes(_ bytes: UInt32) -> String {
+        if bytes >= 1024 {
+            return String(format: "%.1f KB", Double(bytes) / 1024.0)
+        }
+        return "\(bytes) B"
+    }
+}
+
+// MARK: - ViewModel
+
+/// View model driving the App Clip scan-decode flow.
+@MainActor
+final class AppClipViewModel: ObservableObject {
+
+    enum State: Equatable {
+        case scanning
+        case decoding
+        case decoded(SeedInfo)
+        case error(String)
+    }
+
+    @Published var state: State = .scanning
+
+    private let decoder = SeedDecoder()
+
+    /// Handle raw QR payload bytes from the camera scanner.
+    func handleScannedData(_ data: Data) {
+        state = .decoding
+        Task {
+            do {
+                let info = try decoder.decode(data: data)
+                state = .decoded(info)
+            } catch {
+                state = .error(error.localizedDescription)
+            }
+        }
+    }
+
+    /// Decode a built-in demo seed for testing without a camera.
+    func decodeDemoSeed() {
+        // Construct a minimal valid RVQS header (64 bytes) for demonstration.
+        // In production, this would come from a real QR scan.
+        var payload = Data(count: 64)
+        payload.withUnsafeMutableBytes { buf in
+            let p = buf.baseAddress!.assumingMemoryBound(to: UInt8.self)
+
+            // seed_magic = 0x52565153 ("RVQS") in little-endian.
+            p[0] = 0x53; p[1] = 0x51; p[2] = 0x56; p[3] = 0x52
+            // seed_version = 1.
+            p[4] = 0x01; p[5] = 0x00
+            // flags = 0 (minimal).
+            p[6] = 0x00; p[7] = 0x00
+            // file_id = 8 bytes.
+            for i in 8..<16 { p[i] = UInt8(i) }
+            // total_vector_count = 1000 (little-endian).
+            p[0x10] = 0xE8; p[0x11] = 0x03; p[0x12] = 0x00; p[0x13] = 0x00
+            // dimension = 128.
+            p[0x14] = 0x80; p[0x15] = 0x00
+            // base_dtype = 0, profile_id = 0.
+            p[0x16] = 0x00; p[0x17] = 0x00
+            // created_ns = 0 (8 bytes, already zero).
+            // microkernel_offset = 64, microkernel_size = 0.
+            p[0x20] = 0x40; p[0x21] = 0x00; p[0x22] = 0x00; p[0x23] = 0x00
+            // download_manifest_offset = 64, download_manifest_size = 0.
+            p[0x28] = 0x40; p[0x29] = 0x00; p[0x2A] = 0x00; p[0x2B] = 0x00
+            // sig_algo = 0, sig_length = 0.
+            // total_seed_size = 64.
+            p[0x34] = 0x40; p[0x35] = 0x00; p[0x36] = 0x00; p[0x37] = 0x00
+            // content_hash = 8 bytes of 0xAB.
+            for i in 0x38..<0x40 { p[i] = 0xAB }
+        }
+
+        handleScannedData(payload)
+    }
+
+    /// Reset to scanning state.
+    func reset() {
+        state = .scanning
+    }
+}
+
+// MARK: - QR Scanner Coordinator (AVFoundation placeholder)
+
+/// Coordinator for camera-based QR code scanning.
+///
+/// In a full implementation, this would wrap AVCaptureSession with a
+/// metadata output delegate to detect QR codes in real-time.
+/// Kept as a placeholder to show the integration pattern.
+#if canImport(AVFoundation)
+final class QRScannerCoordinator: NSObject, AVCaptureMetadataOutputObjectsDelegate {
+
+    var onSeedScanned: ((Data) -> Void)?
+
+    func metadataOutput(
+        _ output: AVCaptureMetadataOutput,
+        didOutput metadataObjects: [AVMetadataObject],
+        from connection: AVCaptureConnection
+    ) {
+        guard let readable = metadataObjects.first as? AVMetadataMachineReadableCodeObject,
+              readable.type == .qr,
+              let stringValue = readable.stringValue,
+              let data = stringValue.data(using: .utf8)
+        else {
+            return
+        }
+
+        // In production, the QR code would contain raw binary data.
+        // For App Clips invoked via URL, the seed bytes would be
+        // fetched from the URL's associated payload.
+        onSeedScanned?(data)
+    }
+}
+#endif

examples/app-clip/Sources/AppClip/SeedDecoder.swift

@@ -0,0 +1,166 @@
+// SeedDecoder.swift — Swift wrapper for decoding RVQS QR Cognitive Seeds.
+//
+// Calls into the RVF C FFI (librvf_runtime.a) via the RVFBridge module
+// to parse raw seed bytes scanned from a QR code.
+
+import Foundation
+import RVFBridge
+
+// MARK: - SeedInfo
+
+/// Decoded information from an RVQS QR Cognitive Seed.
+struct SeedInfo: Codable, Equatable, Sendable {
+    /// Seed format version.
+    let version: UInt16
+    /// Number of download hosts in the manifest.
+    let hosts: UInt32
+    /// Number of progressive download layers.
+    let layers: UInt32
+    /// SHAKE-256-64 content hash as a hex string.
+    let contentHash: String
+    /// Total vector count the seed references.
+    let totalVectorCount: UInt32
+    /// Vector dimensionality.
+    let dimension: UInt16
+    /// Total seed payload size in bytes.
+    let totalSeedSize: UInt32
+    /// Whether the seed has an embedded WASM microkernel.
+    let hasMicrokernel: Bool
+    /// Whether the seed is cryptographically signed.
+    let isSigned: Bool
+    /// Primary download URL (if available).
+    let primaryHostURL: String?
+}
+
+// MARK: - SeedDecoderError
+
+/// Errors that can occur during seed decoding.
+enum SeedDecoderError: LocalizedError {
+    case emptyData
+    case parseFailed(code: Int32)
+    case urlExtractionFailed(code: Int32)
+
+    var errorDescription: String? {
+        switch self {
+        case .emptyData:
+            return "Seed data is empty."
+        case .parseFailed(let code):
+            return "Seed parse failed with error code \(code)."
+        case .urlExtractionFailed(let code):
+            return "Host URL extraction failed with error code \(code)."
+        }
+    }
+}
+
+// MARK: - SeedDecoder
+
+/// Decodes RVQS QR Cognitive Seeds by calling the RVF C FFI.
+///
+/// Usage:
+/// ```swift
+/// let decoder = SeedDecoder()
+/// let info = try decoder.decode(data: qrPayload)
+/// print(info.contentHash)
+/// ```
+final class SeedDecoder: Sendable {
+
+    init() {}
+
+    /// Decode raw QR seed bytes into a `SeedInfo`.
+    ///
+    /// - Parameter data: The raw RVQS seed payload from a QR code.
+    /// - Returns: Parsed seed information.
+    /// - Throws: `SeedDecoderError` if parsing fails.
+    func decode(data: Data) throws -> SeedInfo {
+        guard !data.isEmpty else {
+            throw SeedDecoderError.emptyData
+        }
+
+        // Parse the 64-byte header via the C FFI.
+        var header = RvqsHeaderC()
+        let parseResult: Int32 = data.withUnsafeBytes { rawBuffer in
+            guard let baseAddress = rawBuffer.baseAddress else {
+                return RVQS_ERR_NULL_PTR
+            }
+            let ptr = baseAddress.assumingMemoryBound(to: UInt8.self)
+            return rvqs_parse_header(ptr, rawBuffer.count, &header)
+        }
+
+        guard parseResult == RVQS_OK else {
+            throw SeedDecoderError.parseFailed(code: parseResult)
+        }
+
+        // Extract primary host URL (best-effort; nil if not available).
+        let primaryURL = extractPrimaryHostURL(from: data)
+
+        // Derive host_count and layer_count from the seed result.
+        // The C FFI provides the header; we infer counts from manifest presence.
+        // For a full implementation, rvf_seed_parse would walk the TLV manifest.
+        // In this skeleton, we report manifest presence via flags.
+        let hasManifest = (header.flags & 0x0002) != 0
+        let hostCount: UInt32 = primaryURL != nil ? 1 : 0
+        let layerCount: UInt32 = hasManifest ? 1 : 0
+
+        // Build the hex string for content_hash.
+        let hashBytes = withUnsafeBytes(of: header.content_hash) { Array($0) }
+        let contentHash = hashBytes.map { String(format: "%02x", $0) }.joined()
+
+        // Check flags.
+        let hasMicrokernel = (header.flags & 0x0001) != 0
+        let isSigned = (header.flags & 0x0004) != 0
+
+        return SeedInfo(
+            version: header.seed_version,
+            hosts: hostCount,
+            layers: layerCount,
+            contentHash: contentHash,
+            totalVectorCount: header.total_vector_count,
+            dimension: header.dimension,
+            totalSeedSize: header.total_seed_size,
+            hasMicrokernel: hasMicrokernel,
+            isSigned: isSigned,
+            primaryHostURL: primaryURL
+        )
+    }
+
+    /// Verify the content hash of a seed payload.
+    ///
+    /// - Parameter data: The raw RVQS seed payload.
+    /// - Returns: `true` if the content hash is valid.
+    func verifyContentHash(data: Data) -> Bool {
+        let result: Int32 = data.withUnsafeBytes { rawBuffer in
+            guard let baseAddress = rawBuffer.baseAddress else {
+                return RVQS_ERR_NULL_PTR
+            }
+            let ptr = baseAddress.assumingMemoryBound(to: UInt8.self)
+            return rvqs_verify_content_hash(ptr, rawBuffer.count)
+        }
+        return result == RVQS_OK
+    }
+
+    // MARK: - Private
+
+    /// Extract the primary download host URL from the seed's TLV manifest.
+    private func extractPrimaryHostURL(from data: Data) -> String? {
+        var urlBuffer = [UInt8](repeating: 0, count: 256)
+        var urlLength: Int = 0
+
+        let result: Int32 = data.withUnsafeBytes { rawBuffer in
+            guard let baseAddress = rawBuffer.baseAddress else {
+                return RVQS_ERR_NULL_PTR
+            }
+            let ptr = baseAddress.assumingMemoryBound(to: UInt8.self)
+            return rvqs_get_primary_host_url(
+                ptr, rawBuffer.count,
+                &urlBuffer, urlBuffer.count,
+                &urlLength
+            )
+        }
+
+        guard result == RVQS_OK, urlLength > 0 else {
+            return nil
+        }
+
+        return String(bytes: urlBuffer[..<urlLength], encoding: .utf8)
+    }
+}