el/lang/swarm/containment.el

// containment.el — the Swarm Architecture containment rules, enforced.
//
// "These rules are not conventions. They are enforced by the runtime."
// (Swarm Architecture §3.2). The three rules that make bounded parallelism —
// and therefore location-independent distribution — safe:
//
//   Rule 1: a worker may NOT join another swarm.
//   Rule 2: a worker may NOT initiate a new swarm.
//   Rule 3: a worker may NOT communicate laterally with sibling workers.
//
// Enforcement is by SCOPE TOKEN. When a swarm fans out, the coordinator mints a
// swarm scope token and stamps a distinct worker scope token into each worker's
// task envelope. Any attempt to create or join a swarm checks the caller's
// token: if the caller already holds a WORKER token, the operation is rejected.
// Rule 3 is enforced structurally elsewhere — workers share no mutable state and
// the only channels they hold are the vertical result path — but this module
// provides the explicit lateral-edge check for the execution tree.
//
// A scope token is a JSON object: {"kind":"coordinator|worker","swarm":"<corr>",
// "worker":"<id-or-empty>","depth":"<n>"}.

// ── Token minting ────────────────────────────────────────────────────────────

// containment_coordinator_token — the token a coordinator holds. Depth 0.
// Only a coordinator token may open a swarm.
fn containment_coordinator_token(corr_id: String) -> String {
    let kv: [String] = el_list_empty()
    let kv = el_list_append(kv, "kind")
    let kv = el_list_append(kv, "coordinator")
    let kv = el_list_append(kv, "swarm")
    let kv = el_list_append(kv, corr_id)
    let kv = el_list_append(kv, "worker")
    let kv = el_list_append(kv, "")
    let kv = el_list_append(kv, "depth")
    let kv = el_list_append(kv, "0")
    return json_build_object(kv)
}

// containment_worker_token — the token stamped into a worker's envelope. Depth 1.
// A worker token is a closed boundary: holding it forbids opening/joining swarms.
fn containment_worker_token(corr_id: String, worker_id: String) -> String {
    let kv: [String] = el_list_empty()
    let kv = el_list_append(kv, "kind")
    let kv = el_list_append(kv, "worker")
    let kv = el_list_append(kv, "swarm")
    let kv = el_list_append(kv, corr_id)
    let kv = el_list_append(kv, "worker")
    let kv = el_list_append(kv, worker_id)
    let kv = el_list_append(kv, "depth")
    let kv = el_list_append(kv, "1")
    return json_build_object(kv)
}

// ── Rule checks (return "" on allow, or a rejection reason string) ───────────

// containment_check_open — may the holder of `token` OPEN a new swarm?
// Enforces Rule 2 (a worker may not initiate a new swarm). Only a coordinator
// token, or an absent token (top-level process), may open one.
fn containment_check_open(token: String) -> String {
    if str_eq(token, "") {
        return ""
    }
    let kind: String = json_get_string(token, "kind")
    if str_eq(kind, "worker") {
        return "CONTAINMENT rule 2: a swarm worker may not initiate a new swarm (worker=" + json_get_string(token, "worker") + " swarm=" + json_get_string(token, "swarm") + ")"
    }
    return ""
}

// containment_check_join — may the holder of `token` JOIN swarm `target_corr`?
// Enforces Rule 1 (a worker may not join another swarm). A worker already bound
// to swarm A may not register into swarm B; and a worker may not re-join at all.
fn containment_check_join(token: String, target_corr: String) -> String {
    if str_eq(token, "") {
        return ""
    }
    let kind: String = json_get_string(token, "kind")
    if str_eq(kind, "worker") {
        return "CONTAINMENT rule 1: a swarm worker may not join another swarm (worker=" + json_get_string(token, "worker") + " bound-swarm=" + json_get_string(token, "swarm") + " attempted-swarm=" + target_corr + ")"
    }
    return ""
}

// containment_check_lateral — may `from_token` open a communication edge to a
// sibling worker `to_worker_id`? Enforces Rule 3 (no lateral communication).
// The only permitted edges are vertical: worker->coordinator and
// coordinator->worker. Any worker->worker edge is rejected.
fn containment_check_lateral(from_token: String, to_worker_id: String) -> String {
    let kind: String = json_get_string(from_token, "kind")
    if str_eq(kind, "worker") {
        if str_eq(to_worker_id, "") {
            // empty target = the coordinator (vertical) — allowed
            return ""
        }
        return "CONTAINMENT rule 3: a swarm worker may not communicate laterally with sibling workers (from=" + json_get_string(from_token, "worker") + " to=" + to_worker_id + ")"
    }
    return ""
}

// ── Enforcement helpers ──────────────────────────────────────────────────────

// containment_allows_open — Bool convenience over containment_check_open.
fn containment_allows_open(token: String) -> Bool {
    return str_eq(containment_check_open(token), "")
}

// containment_is_worker — is this a worker-scoped (closed-boundary) token?
fn containment_is_worker(token: String) -> Bool {
    return str_eq(json_get_string(token, "kind"), "worker")
}

// containment_guard_open — assert a swarm may be opened under this token.
// Returns "" if allowed, or records a CONTAINMENT violation to the work-tracking
// journal and returns the reason. Callers must abort on a non-empty return.
fn containment_guard_open(token: String, corr_id: String) -> String {
    let reason: String = containment_check_open(token)
    if str_eq(reason, "") {
        return ""
    }
    let p: String = json_set("{}", "reason", reason)
    worktrack_append("containment.violation", corr_id, "open", p)
    return reason
}