const std = @import("std");

pub fn parse_kv_pair(input: []const u8, allocator: std.mem.Allocator) !struct { key: []u8, value: []u8 } {
    const delimiter = std.mem.indexOfScalar(u8, input, '=') orelse return error.InvalidFormat;
    const k = try allocator.dupe(u8, input[0..delimiter]);
    const v = try allocator.dupe(u8, input[delimiter + 1..]);
    return .{ .key = k, .value = v };
}

use std::collections::HashMap;

pub fn extract_key_value(input: &str) -> Result<(String, String), ParseError> {
    let (key, value) = input.split_once('=').ok_or(ParseError::MissingDelimiter)?;
    Ok((key.trim().to_string(), value.trim().to_string()))
}

#[derive(Debug)]
pub enum ParseError {
    MissingDelimiter,
}

g codebase, and route calls through the C ABI until the migration is complete.

Architecture Decision: Never expose Rust or Zig types directly across the boundary. Serialize all data to C-compatible primitives (*const c_char, uint32_t, raw pointers) and handle memory ownership explicitly on one side. This prevents double-free scenarios and ABI mismatch crashes.

Step 3: Align Allocator Strategies

Memory management semantics differ fundamentally. Zig often relies on arena allocators or explicit std.mem.Allocator instances passed through call stacks. Rust defaults to the system allocator but supports custom allocators via the Allocator trait.

Implementation Choice: If the original codebase heavily uses arena-based allocation for request-scoped data, replicate this in Rust using bumpalo or typed-arena. Do not blindly replace arenas with Vec or Box, as this introduces fragmentation and changes cache locality patterns under sustained load.

Step 4: Parallel Test Execution & Divergence Detection

Run the original test suite against both implementations simultaneously. Use a test harness that feeds identical inputs to the Zig and Rust binaries, compares outputs, and logs discrepancies. This catches subtle behavioral drift caused by different standard library implementations, floating-point handling, or error propagation models.

Pitfall Guide

1. Assuming Test Parity Equals Behavioral Parity

Explanation: Passing 99.8% of tests does not guarantee identical runtime behavior. Tests often cover happy paths and known edge cases. They rarely simulate sustained memory pressure, concurrent FFI calls, or platform-specific syscalls. Fix: Implement property-based testing (e.g., proptest in Rust) alongside the existing suite. Inject fuzzing targets at FFI boundaries and monitor memory allocation patterns under load.

2. Ignoring Allocator Semantics

Explanation: Swapping explicit Zig allocators for Rust's default allocator changes memory layout, fragmentation behavior, and cache hit rates. Arena allocators provide O(1) deallocation; replacing them with heap allocations can degrade throughput by 15-30% in high-churn scenarios. Fix: Profile memory allocation hotspots before migrating. If arenas are critical, integrate a Rust arena crate and maintain the same allocation lifecycle. Document ownership boundaries explicitly.

3. FFI Boundary Leaks

Explanation: Crossing language boundaries with complex types (strings, slices, structs) often leads to mismatched memory layouts or ownership confusion. One language may free memory the other still references, causing use-after-free crashes. Fix: Enforce a strict C ABI contract. Pass only primitive types or raw pointers. Define clear ownership rules: the caller allocates, the callee borrows, or vice versa. Never return allocated memory across the boundary without an explicit deallocation function.

4. Concurrency Model Mismatch

Explanation: Zig relies on explicit thread spawning and manual synchronization. Rust enforces thread safety through Send and Sync traits. Migrating concurrent code without adapting to Rust's ownership model often results in excessive Arc<Mutex<T>> usage, creating lock contention bottlenecks. Fix: Audit concurrent pathways. Replace coarse-grained locks with channel-based communication (mpsc, tokio::sync) or lock-free data structures where applicable. Leverage Rust's type system to prove thread safety at compile time rather than runtime.

5. Toolchain & Build System Drift

Explanation: Zig's build system and Rust's Cargo have different dependency resolution, caching, and cross-compilation strategies. Blindly porting build scripts leads to longer CI times, missing native dependencies, or inconsistent release binaries. Fix: Rebuild the CI/CD pipeline from scratch. Use cargo-zigbuild or cross for deterministic cross-compilation. Cache build artifacts aggressively and benchmark compile times early to set realistic developer expectations.

6. Over-Optimizing the Rewrite

Explanation: Engineers often refactor logic, improve algorithms, and add features during migration. This introduces new bugs, delays delivery, and makes parity verification impossible. Fix: Enforce a strict "port first, optimize later" policy. The initial migration must replicate existing behavior exactly. Performance improvements and architectural refinements belong in a separate phase after parity is proven.

7. Underestimating Plugin & Native Module Impact

Explanation: Runtime rewrites often shift internal APIs, change extension loading mechanisms, or alter native module compilation targets. Third-party plugin authors face breaking changes, causing ecosystem fragmentation. Fix: Maintain backward-compatible extension interfaces during the transition. Provide migration guides, deprecation timelines, and compatibility shims. Communicate API changes early to plugin maintainers.

Production Bundle

Action Checklist

• Audit dependency graph: Identify leaf modules with zero external dependencies for initial migration.
• Define FFI contract: Establish strict C ABI boundaries with explicit ownership rules and primitive-only data transfer.
• Align allocator strategy: Profile memory patterns and select a Rust allocator (system, bumpalo, or custom) that matches original behavior.
• Build parallel test harness: Run Zig and Rust implementations side-by-side with identical inputs to detect behavioral drift.
• Implement property-based testing: Add fuzzing and randomized input generation to catch edge cases missed by deterministic tests.
• Reconstruct CI/CD pipeline: Replace build scripts with language-native tooling, configure cross-compilation, and benchmark compile times.
• Document extension compatibility: Create migration guides and compatibility layers for native module authors before public release.
• Schedule post-migration optimization: Defer algorithmic improvements and refactoring until parity is verified and stable.

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Small utility library (<10k LOC)	Direct rewrite with full test port	Low risk, fast iteration, minimal FFI overhead	Low (1-2 weeks)
Mid-size service with external deps	C ABI bridge + incremental module replacement	Maintains stability, allows parallel development	Medium (1-3 months)
Large runtime with FFI/JS bindings	Strict boundary isolation + allocator alignment	Prevents memory leaks, ensures predictable performance	High (3-6 months)
Team lacks target language expertise	Hire specialist + pair programming + strict code review	Reduces architectural debt, accelerates onboarding	High upfront, low long-term
Tight deadline, stability critical	Maintain original language, optimize hot paths	Avoids migration risk, delivers predictable results	Low (immediate)

Configuration Template

A minimal Cargo.toml and build.zig setup for cross-compilation and FFI bridging:

Cargo.toml

[package]
name = "runtime_bridge"
version = "0.1.0"
edition = "2021"

[lib]
crate-type = ["staticlib", "cdylib"]

[dependencies]
bumpalo = "3.14"
serde = { version = "1.0", features = ["derive"] }

[profile.release]
lto = true
codegen-units = 1
opt-level = 3

build.zig

const std = @import("std");

pub fn build(b: *std.Build) void {
    const target = b.standardTargetOptions(.{});
    const optimize = b.standardOptimizeOption(.{});

    const exe = b.addExecutable(.{
        .name = "host_runner",
        .root_source_file = b.path("src/main.zig"),
        .target = target,
        .optimize = optimize,
    });

    exe.linkLibC();
    exe.linkSystemLibrary("runtime_bridge");
    exe.addLibraryPath(b.path("../target/release"));

    b.installArtifact(exe);
}

Quick Start Guide

1. Initialize the bridge module: Create a new Rust crate with cargo init --lib runtime_bridge. Configure crate-type = ["staticlib"] in Cargo.toml to produce a linkable binary.
2. Define the C ABI interface: Write extern "C" functions in Rust that accept raw pointers and primitive types. Implement explicit allocation/deallocation functions to manage cross-language memory.
3. Compile and link: Run cargo build --release to generate the static library. Update the Zig build script to link against the compiled artifact using linkSystemLibrary and addLibraryPath.
4. Validate parity: Write a minimal test in Zig that calls the Rust function, passes known inputs, and asserts output equality. Run under valgrind or AddressSanitizer to detect memory violations.
5. Iterate incrementally: Replace one Zig module at a time. Maintain the C bridge until the entire codebase is migrated, then remove the interop layer and unify the build system.