// neuron.el — Neuron intelligence entry point.
//
// This is the root module loaded by neuron-runtime at startup. It wires
// all subsystems together and defines the swarm coordinator — the function
// that handles every incoming tool call.
//
// Architecture intent:
// Neuron is a swarm agent: one coordinator orchestrates multiple specialized
// subsystems (memory, knowledge, backlog, context, artifact, etc.). Each
// subsystem is a focused el module. The coordinator dispatches
// to the right subsystem based on tool_name.
//
// The @swarm_coordinator decorator tells the engram runtime that this function
// is the root entry point for the agent. The runtime calls handle_tool_call()
// for every incoming Axon message.
//
// Startup sequence (enforced by the runtime):
//   1. Load types.el         — graph schema registration
//   2. Load all subsystems   — function registration
//   3. Load axon.el          — dispatch table
//   4. Load neuron.el        — entry point wiring
//   5. Call version()        — runtime health check
//
// This file intentionally contains minimal logic. It's the composition
// root, not a logic layer. Keep it thin.

from axon import { dispatch_tool }
from types import { NeuronError }

// ── Swarm coordinator ─────────────────────────────────────────────────────────

// handle_tool_call — the root entry point for all Axon tool invocations.
//
// The @swarm_coordinator decorator registers this function as the agent's
// primary message handler. The runtime calls it for every incoming tool call
// after authentication is verified at the protocol layer.
//
// It delegates entirely to dispatch_tool() in axon.el — the coordinator
// should not contain routing logic.
@swarm_coordinator
fn handle_tool_call(
    tool_name: String,
    params: Map<String, String>,
) -> Result<Map<String, String>, NeuronError> {
    dispatch_tool(tool_name, params)
}

// ── Health and metadata ───────────────────────────────────────────────────────

// version — return the current Neuron version string.
//
// @public — called by the runtime health check without authentication.
// The format is "neuron/<version>-engram" to distinguish from the Kotlin
// predecessor (which used "neuron/<version>-kotlin").
@public
fn version() -> String {
    "neuron/1.0.0-engram"
}

// health — lightweight liveness probe.
//
// Returns "ok" if the engram runtime and all subsystems loaded correctly.
// Called by the /health HTTP endpoint in neuron-api.
@public
fn health() -> String {
    "ok"
}

// ── Session bootstrap ─────────────────────────────────────────────────────────

// on_startup — called once when the runtime initializes.
//
// Emits a startup event so Axon subscribers know Neuron is ready.
// Does NOT run begin_session() — that's the caller's responsibility.
// The runtime calls on_startup() once; callers call begin_session() per session.
@manager
fn on_startup() -> Result<String, NeuronError> {
    native_emit("neuron.started", {"version": "1.0.0-engram"})
    Ok("neuron ready")
}