Zephaniah: Gradual Ownership & Ergonomic ARC

1. Why Zephaniah Exists

While base Nyx uses region bump arenas and compile-time escape proofs (achieving 82.4% bump ratios), certain domains—such as rapid web prototyping, UI view controllers, script automation, and event listeners—involve complex graph topologies and cyclical references where lifetime reasoning slows down iteration.

Zephaniah solves this: It allows developers to opt into progressive strictness. If an allocation escapes without an explicit region context, Zephaniah automatically wraps it in an atomic or thread-local reference-counted container (Arc<T>), requiring zero manual lifetime annotations.

Feature	Base Nyx (.nyx)	Zephaniah (.zeph)
Primary Memory Strategy	Zero-GC Region Bump Arenas + Escape Analysis	Gradual Ownership + Automatic ARC Fallback
Lifetime Annotations	Explicit when escaping regional contexts	None (Inferred or transparently refcounted)
Complex Graph Structures	Requires arena allocation or generational IDs	Natural bidirectional references via weak pointers
Compilation Speed	Ultra-fast single-pass MLIR lowering	Same high-speed MLIR backend with ARC emission

2. Syntax & Gradual Ownership Rules

In Zephaniah, references are shared by default, and ownership can be progressively tightened using @owned or linear parameters:

// file: server_session.zeph
// Compile with: nyxc --mode=gradual server_session.zeph -o session_mgr.exe

struct ClientSession {
    id: u64,
    username: String,
    metadata: Map<String, String>,
}

fn handle_connection(session: ClientSession) {
    // Transparently shared ARC reference - no lifetime parameters required
    println("Connected: {session.username} (ID: {session.id})");
    
    // Gradual ownership handover: @owned enforces single-consumer transfer
    dispatch_to_worker(@owned session);
}

fn dispatch_to_worker(owned_session: @owned ClientSession) {
    // Zero-copy move: refcount drops to 1, converted into unshared owned frame
    println("Worker background thread processing: {owned_session.username}");
}

3. Concrete Industrial Use Cases

Use Case 1: High-Throughput Fintech Payment Gateway API

Handling asynchronous webhooks from multiple bank switches and card rails requires parsing deeply nested JSON payloads and sharing parsed transaction graphs across asynchronous verification tasks without fighting lifetime parameters:

import std.net.http;
import std.json;
import std.async;

struct PaymentPayload {
    transaction_id: String,
    amount_kobo: u64,
    sender_account: String,
    beneficiary_account: String,
    bank_routing_code: String,
}

pub async fn handle_payment_webhook(req: HttpRequest) -> HttpResponse {
    // Parse nested payload with automatic ARC memory management
    let payload = json::parse<PaymentPayload>(&req.body);

    if payload.amount_kobo == 0 {
        return HttpResponse::bad_request("Invalid payment amount");
    }

    // Share transaction reference simultaneously with Fraud Engine and Audit Logger
    let fraud_check = async::spawn(verify_fraud_rules(payload.clone()));
    let audit_log   = async::spawn(write_audit_trail(payload.clone()));

    let (fraud_ok, _) = async::join(fraud_check, audit_log).await;

    if !fraud_ok {
        return HttpResponse::forbidden("Transaction flagged by anti-fraud heuristic");
    }

    // Hand over owned payload to core banking settlement pipeline
    let settlement_status = execute_nibss_instant_payment(@owned payload).await;
    HttpResponse::ok(settlement_status.to_json())
}

Use Case 2: Pan-African Multilingual Production Banking Microservice

Zephaniah lets engineering teams author mission-critical services directly in Yorùbá, Hausa, or Igbo, natively lowering to high-performance machine code:

// file: ile_ifowopamo.zeph (Yorùbá Microservice)
ìṣètò Oníbàárà {
    orúkọ: Ọ̀rọ̀,
    nọ́mbà_àkọọ́lẹ̀: Ọ̀rọ̀,
    owó_tó_wà: Oye,
}

iṣẹ́ fi_owó_ránṣẹ́(oníbàárà: Oníbàárà, iye_owó: Oye, olugba: Ọ̀rọ̀) -> Otitọ {
    nígbàtí (oníbàárà.owó_tó_wà >= iye_owó) {
        oníbàárà.owó_tó_wà -= iye_owó;
        tẹ̀wé("A ti fi #{iye_owó} kobo ránṣẹ́ sí #{olugba} fún #{oníbàárà.orúkọ}");
        padà Otitọ::Bẹ́ẹ̀ni;
    }
    tẹ̀wé("Owó kò tó nínú àkọọ́lẹ̀ #{oníbàárà.nọ́mbà_àkọọ́lẹ̀}");
    padà Otitọ::Bẹ́ẹ̀kọ́;
}

Use Case 3: Real-Time Collaborative WebSockets (100k+ Connections)

In collaborative canvas and chat backends, thousands of client sockets subscribe to dynamically changing room channels. Zephaniah cleans up room subscriptions automatically when clients disconnect:

import std.net.websocket;
import std.collections.map;

struct BroadcastChannel {
    room_id: String,
    subscribers: List<Weak<WebSocketConnection>>,
}

impl BroadcastChannel {
    pub fn broadcast(&mut self, message: String) {
        // Automatically prune disconnected clients whose weak references expired
        self.subscribers.retain(|weak_client| {
            if let Some(client) = weak_client.upgrade() {
                client.send_text(&message);
                true
            } else {
                false // Dropped automatically without leak
            }
        });
    }
}

Use Case 4: Rapid GUI Desktop & Dashboard Controllers

Building UI widgets and reactive state controllers in Material Design 3 requires circular parent-child references. Zephaniah handles widget tree mutations seamlessly:

import std.ui.material;

struct DashboardController {
    selected_account: Option<String>,
    view_tree: UiNode,
}

pub fn create_analytics_view() -> DashboardController {
    let mut root = UiNode::column();
    let header = UiNode::text("Enterprise Treasury Overview", Style::HeadingLarge);
    let chart  = UiNode::line_chart(data_source: "/api/v1/metrics/cashflow");

    root.add_child(header);
    root.add_child(chart);

    DashboardController {
        selected_account: None,
        view_tree: root,
    }
}