DEV Community: clojure

Embabel agents as Clojure data

João Hornos — Thu, 20 Aug 2026 19:22:32 +0000

What Embabel is

Embabel is an agent framework for the
JVM, built on Spring by Rod Johnson. Its distinguishing bet is stated plainly in
the docs: instead of a finite state machine or a sequential chain with nesting,
it introduces a true planning step, using a non-LLM AI algorithm.

The vocabulary is small. From the framework's own Core Concepts:

Actions — steps an agent takes.
Goals — what an agent is trying to achieve.
Conditions — evaluated while planning, and reassessed after each action.
Domain Model — the objects underpinning the flow.

From those, the framework builds a plan: a sequence of actions that reaches a
goal.

Plans are dynamically formulated by the system, not the programmer.

Planning is Goal-Oriented Action Planning, or GOAP. After every action the
framework looks at the world again, searches with A* for the cheapest path from
where it now is to the goal, and executes the next step. The docs call the result
an OODA loop: observe, orient, decide, act. The practical consequence is that
nothing in your code says "first check stock, then pick, then pack". You
declare what each action needs and what it produces, and the order is derived.

State lives in a blackboard, the shared memory of one agent process. Actions
read their inputs from it and their return values are added to it automatically;
conditions are evaluated against its contents. A process moves through explicit
states: RUNNING, COMPLETED, WAITING, FAILED, and STUCK, which the docs
define as "the process cannot formulate a plan to progress".

That is the whole conceptual surface. Two annotations and a domain model in Java
or Kotlin, and the framework infers the rest, conditions included: a method
signature retrieveHoroscope(StarPerson) is the precondition "a StarPerson
exists", and its return type is the postcondition.

Why Clojure

Actions with preconditions, postconditions and costs. Goals with values.
Conditions that are names with truth values. A blackboard that is a bag of named
things. That is a graph plus a table of numbers: a world model. It is data, and
the framework searches it with A*.

In Java and Kotlin that model is expressed indirectly, through the type system
and annotations: the compiler and AgentMetadataReader extract the graph from
your class. That works, and the type inference in the annotated model is
genuinely clever. But the graph itself never exists as a value you can hold.

Clojure's whole proposition is that data is the interface. So the question this
library asks is narrow and testable:

If the planner's world model is a data structure, what happens when you write
it as one, literally, as a value?

Four things follow, and this post checks each one:

The agent becomes a value. You can pprint it, diff two versions, store it as EDN, generate it, send it over a wire.
The LLM speaks the language's own data syntax. When a model answers with {:biome "Taiga" :confidence 0.8}, edn/read-string hands you a Clojure map. No Jackson, no POJO, no binding layer.
Schemas are data too. One malli schema generates the prompt, validates the answer, coerces the types, and re-asks the model on failure.
The REPL runs against a live platform. Redefine an action body and run again, with no rebuild and no redeploy.

None of this is an argument that you should write Embabel agents in Clojure
rather than in Kotlin or Java. The framework is excellent in its home languages
and the annotated model is the shortest path for most people. This post is about
what a different representation makes possible, and what it costs.

A Rosetta stone: the same agent, in both languages

Before any Clojure, here is the agent the Embabel documentation itself uses to
introduce the framework: StarNewsFinder, shortened to three actions. If you
have read the docs, you have seen this:

@Agent(description = "Find news based on a person's star sign")
class StarNewsFinder(
    private val horoscopeService: HoroscopeService,
) {

    @Action
    fun extractStarPerson(userInput: UserInput, context: OperationContext): StarPerson =
        context.ai()
            .withLlm(OpenAiModels.GPT_41)
            .createObject("Create a person from this user input…", StarPerson::class)

    @Action
    fun retrieveHoroscope(starPerson: StarPerson): Horoscope =
        Horoscope(horoscopeService.dailyHoroscope(starPerson.sign))

    @AchievesGoal(description = "Write an amusing writeup")
    @Action
    fun writeup(person: StarPerson, horoscope: Horoscope, context: OperationContext): Writeup =
        context.ai().withDefaultLlm().createObject("Write something amusing…", Writeup::class)
}

Nothing there declares the order, and nothing declares the conditions. The
framework reads both off the type signatures:

extractStarPerson(UserInput) → precondition "a UserInput exists"; returning StarPerson → postcondition "a StarPerson now exists".
retrieveHoroscope(StarPerson) therefore cannot run before it.
@AchievesGoal marks the terminal action, so the goal is "produce a Writeup".

Nobody wrote the plan UserInput → extractStarPerson → retrieveHoroscope → writeup. The framework derived it.

Now the same structure in Clojure. The shape is different but the pieces map one
to one; read the map keys as the annotations they replace:

(deftype StarPerson [name sign])
(deftype Horoscope  [summary])
(deftype Writeup    [text])

(def star-news
  (ec/agent
   {:name        "star-news-finder"
    :description "Find news based on a person's star sign"

    ;; @AchievesGoal — the goal is a type that must exist
    :goals   [{:name "written" :description "an amusing writeup"
               :inputs [{:name "writeup" :type Writeup}] :value 1.0}]

    :actions
    [;; @Action fun extractStarPerson(userInput: UserInput): StarPerson
     {:name    "extract-star-person"
      :inputs  [{:name "input"  :type UserInput}]
      :outputs [{:name "person" :type StarPerson}]
      :llm?    true
      :fn (fn [ctx]
            (let [{:keys [name sign]}
                  (schema/create-edn! ctx {:schema Person
                                           :llm    "openai/gpt-4.1"
                                           :prompt "Create a person from this user input…"})]
              (bb/put! ctx "person" (->StarPerson name sign))))}

     ;; @Action fun retrieveHoroscope(starPerson: StarPerson): Horoscope
     {:name    "retrieve-horoscope"
      :inputs  [{:name "person"    :type StarPerson}]
      :outputs [{:name "horoscope" :type Horoscope}]
      :fn (fn [ctx]
            (let [p (bb/fetch ctx "person")]
              (bb/put! ctx "horoscope"
                       (->Horoscope (horoscope-service/daily (.sign p))))))}

     ;; @AchievesGoal @Action fun writeup(person, horoscope): Writeup
     {:name    "writeup"
      :inputs  [{:name "person" :type StarPerson} {:name "horoscope" :type Horoscope}]
      :outputs [{:name "writeup" :type Writeup}]
      :llm?    true
      :fn (fn [ctx]
            (bb/put! ctx "writeup"
                     (->Writeup (schema/ask ctx {:prompt "Write something amusing…"}))))}]}))

Same graph, same derivation, same plan. What moved is where the graph lives: in
Kotlin it is implied by the signatures and recovered by an annotation reader; in
Clojure it is written out as a value.

The full correspondence:

Embabel (Kotlin/Java)	embabel-clj
`@Agent` class	`(ec/agent {…})` — one map
`@Action fun` + annotation fields	`{:name … :pre […] :post […] :cost 0.1 :rerun? true :fn (fn [ctx] …)}`
parameter types (implicit precondition)	`:inputs [{:name "person" :type StarPerson}]`
return type (implicit postcondition)	`:outputs [{:name "person" :type StarPerson}]`
`@Condition fun` (lazy, on demand)	`{:name :co/needs-evidence? :fn (fn [ctx] …)}` under `:conditions`
`@AchievesGoal` on the terminal action	`{:name "done" :pre […] :value 1.0}` under `:goals`
`blackboard.set` / `getCondition` / `setCondition`	`bb/put!` · `bb/fetch` · `bb/condition?` · `bb/set-condition!`
`createObject<T>()` (Jackson → data class)	`(schema/create-edn! ctx {:schema …})` (EDN → malli)
`ProcessOptions` / `Budget` / planner	`{:options {:budget {…} :planner :goap}}`
`AgenticEventListener` class	`{:options {:listeners [(fn [ev] …)]}}`
`EarlyTerminationPolicy` / `StuckHandler` class	a fn under `:early-termination` / `:stuck-handler`
`@Bean` in a `@Configuration` class	`{:beans {:myService (reify …)}}` in `platform/start!`
`@SpringBootApplication` + your pom	`(platform/start! {…})`

If you prefer the annotations

There is a third form, my own favourite, and it is the closest of all to the
Kotlin. Clojure vars carry metadata, so the annotation model translates almost
literally: tags on a defn, read by agent-from-ns.

Here is the same StarNewsFinder, a third time. Compare it with the Kotlin
above and the layout on the page corresponds too: one function per action, the
annotation directly above the body, the docstring where the description was.

(ns starnews
  (:require [embabel-clj.core :as ec]
            [embabel-clj.blackboard :as bb]
            [embabel-clj.schema :as schema]))

;; the domain types — deftype, not defrecord (see the warning below)
(deftype StarPerson [name sign])
(deftype Horoscope  [summary])
(deftype Writeup    [text])

;; @Action
;; fun extractStarPerson(userInput: UserInput, ctx): StarPerson
(defn extract-star-person
  "Create a person from the user input, extracting name and star sign."
  {:action/post    []                     ; <- the tag that MARKS the var as an action
   :action/inputs  ["input:com.embabel.agent.domain.io.UserInput"]
   :action/outputs ["person:starnews.StarPerson"]
   :action/llm     true}
  [ctx]
  (let [{:keys [name sign]}
        (schema/create-edn! ctx {:schema Person
                                 :llm    "openai/gpt-4.1"
                                 :prompt "Create a person from this user input"})]
    (bb/put! ctx "person" (->StarPerson name sign))))

;; @Action
;; fun retrieveHoroscope(starPerson: StarPerson): Horoscope
(defn retrieve-horoscope
  "Retrieve today's horoscope for the person's sign."
  {:action/post    []
   :action/inputs  ["person:starnews.StarPerson"]
   :action/outputs ["horoscope:starnews.Horoscope"]}
  [ctx]
  (let [p (bb/fetch ctx "person")]
    (bb/put! ctx "horoscope" (->Horoscope (horoscope-service/daily (.sign p))))))

;; @AchievesGoal(description = "Write an amusing writeup")
;; @Action
;; fun writeup(person, horoscope, ctx): Writeup
(defn writeup
  "Write an amusing piece based on the horoscope."
  {:action/post    []
   :action/inputs  ["person:starnews.StarPerson"
                    "horoscope:starnews.Horoscope"]
   :action/outputs ["writeup:starnews.Writeup"]
   :action/llm     true}
  [ctx]
  (bb/put! ctx "writeup"
           (->Writeup (schema/ask ctx {:prompt "Write something amusing"}))))

;; and the whole agent is the namespace scan
(def star-news
  (ec/agent-from-ns 'starnews
    {:name        "star-news-finder"
     :description "Find news based on a person's star sign"
     :goals [{:name        "written"
              :description "an amusing writeup"        ; the @AchievesGoal
              :inputs      ["writeup:starnews.Writeup"]
              :value       1.0}]}))

The correspondence, annotation by tag:

Kotlin	metadata tag
`@Action`	`:action/post` (present, even if empty)
parameter types	`:action/inputs ["name:pkg.Type"]`
return type	`:action/outputs ["name:pkg.Type"]`
`@Action(canRerun = true)`	`:action/rerun true`
planning cost	`:action/cost 0.2`
KDoc / `description`	the docstring, which becomes `description` by itself
`@Condition fun`	`:condition/name :co/something?`
`@AchievesGoal`	a goal in the `opts` map (see below)

The type strings take the form "binding-name:FQCN". That is what the tags
accept, and it breaks in fewer places: metadata is read when the var is defined,
so a string requires neither the class to be loaded already nor the namespace's
imports to be in the right order. deftype generates the class in
the namespace's package, hence starnews.StarPerson.

One difference that cannot be hidden. In Kotlin @AchievesGoal sits on the
terminal action: the action and the goal are one declaration. With
agent-from-ns the goal goes into the opts map, apart from the actions. That
is less elegant, and it is fair to say why. The scan reads vars one at a time,
and a goal needs its own name, value and precondition, which does not fit in the
signature of the function achieving it. What you get in exchange is that the
agent's goals end up listed in one place, which helps when there are several (a
terminal one and a fallback, the common case).

[!warning] The tag that decides whether your function exists
The action detector is literally (contains? (meta v) :action/post). The
presence of the :action/post key is what marks a var as an action.
:action/inputs, :action/outputs and the docstring do not.

With named conditions this goes unnoticed, because every action has a real
:post. In the typed layer it bites: a function with :action/outputs and no
:action/post is silently ignored by the scan. If all of them are like that,
agent-from-ns throws "no var with :action/post metadata"; if only one is,
you get an incomplete agent and a STUCK to investigate.

That is why :action/post [] appears on all three actions above. Empty but
present: it declares no postcondition, since :action/outputs does the
chaining, and exists only to tell the scan "this var is an action".

The reason I prefer this form comes last. agent-from-ns registers the fns as
vars, not values, so redefining a defn in the REPL takes effect on the next
run, with no redeploy and without rebuilding the agent. With the platform up, the
edit cycle for an action body is recompile-the-function and run again, which is
why I wrote the library in the first place.

The same tags, with named conditions

The star-news above is typed, so it uses no conditions at all. In the other
layer the tags show up in full: :action/pre and :action/post with real
conditions, and the lazy @Condition, the one tag with no sibling in the action
map.

(defn generate-verify
  "Generate candidate e-mails and verify them."
  {:action/pre  [:co/domain-known?]
   :action/post [:mail/verified?]
   :action/cost 0.2
   :action/rerun true
   :action/llm  true}
  [ctx] …)

(defn needs-evidence?
  {:condition/name :co/needs-evidence?}      ; a lazy @Condition
  [ctx]
  (and (not (bb/condition? ctx :co/evidence-ready?))
       (bb/condition? ctx :co/ambiguous?)))

(ec/agent-from-ns 'my.agents.hunter
  {:name  "email-hunter" :description "…"
   :goals [{:name "email-found" :pre [:mail/verified?] :value 1.0}]})

Note that needs-evidence? carries no :action/post at all. It is a condition,
and :condition/name is what marks it. The scan tells the two families of var
apart by those two keys, and only those.

[!warning] In the typed layer, use deftype, not defrecord
The obvious Clojure choice for a domain type is defrecord, and it is the
wrong one here. Two properties of records collide with type-based matching on
the blackboard, and both have tests in the repo.

One: every defrecord is a java.util.Map. A map-shaped value counts as
bound without its type being checked, so a goal requiring a Fatura completes
with a Produto on the blackboard. With deftype, the same run correctly
reports STUCK.

Two: defrecord's .equals is map equality without the type. Hidden
objects are kept in a Set, so hiding one record also hides unrelated records
that happen to have the same field values.

deftype is not a Map and compares by identity. It avoids both.

The hook: an agent is 626 bytes

Here is an entire working agent as a literal: four actions, one goal, the
complete plan graph.

{:name        "order"
 :description "Checks stock, picks, packs and ships an order"
 :goals       [{:name "shipped" :description "order on its way" :pre ["delivered"]}]
 :actions     [{:name "check-stock" :description "checks the stock"
                :post ["checked"]   :cost 0.1 :body :body/check-stock}
               {:name "pick"        :description "picks into boxes"
                :pre ["checked"]    :post ["picked"]    :cost 0.2 :body :body/pick}
               {:name "pack"        :description "seals the box"
                :pre ["picked"]     :post ["packed"]    :cost 0.2 :body :body/pack}
               {:name "ship"        :description "hands over to the carrier"
                :pre ["packed"]     :post ["delivered"] :cost 0.5 :body :body/ship}]}

pr-str that and you get 626 bytes of EDN. Write it to disk, read it back in
a different JVM, resolve the four :body keywords against a registry of
functions, and it runs: ["check-stock" "pick" "pack" "ship"], COMPLETED.

Open the .edn file in a text editor and delete the pack action. Run again,
with no recompilation and no code touched:

edit, made only in the data file	what the planner does
delete the `pack` action	goal unreachable → `STUCK`
change `ship`'s precondition to `"picked"`	plan becomes `["check-stock" "pick" "ship"]`

The topology of the plan is in the file. That EDN has 58 scalar leaves, of
which 54 are data and 4 are references to function bodies: 93.1% data. The
remaining 6.9% is the honest part, because a data format can name a behavior but
cannot contain it. A YAML agent spec would hit exactly the same ceiling.

So the agent's definition is data and its bodies are code. The rest of this post
is what that buys.

Getting a platform, without a Java shell

Embabel is a Spring framework. Normally you get an App.java with
@SpringBootApplication, a Maven pom, and a build step. The library removes all
three from your project:

(require '[embabel-clj.platform :as platform])

(def sys
  (platform/start!
   {:properties {:embabel.agent.platform.models.openai.base-url "https://openrouter.ai/api"
                 :embabel.agent.platform.models.openai.api-key  (System/getenv "OPENROUTER_APIKEY")
                 :embabel.models.default-llm "openai/gpt-4o-mini"}}))

(:platform sys)   ;; => the live AgentPlatform

There is no src-java directory behind that call and no javac in the build.
The @SpringBootApplication class is an empty gen-class carrying the
annotation as metadata, compiled on demand at runtime into a temp dir and
defined straight into Clojure's DynamicClassLoader. Add the library as a git
dep or a :local/root and the first start! produces the class. Nothing to
prepare, ever.

Two details that are not cosmetic:

Properties are passed as command-line args (--k=v), which is the highest precedence Spring offers. The obvious alternative, builder.properties(), is defaultProperties, the lowest precedence, and loses to the framework's own embedded defaults. That was found the hard way when embabel.models.default-llm refused to take effect.
Your own Spring beans don't need a @Configuration class. :beans goes in through an ApplicationContextInitializer, which runs before the context refresh, so a plain reify can be registered as a ready-made singleton. Since Embabel resolves LlmService, EmbeddingService and friends by type, a reified interface is indistinguishable from an @Bean.

(platform/start!
 {:properties   {…}
  :beans        {:myLlmService (reify com.embabel.agent.spi.LlmService …)}
  :initializers [(fn [ctx] (.setId ctx "my-context"))]})

This is the interop tax. It is real, and it is paid once, inside the library,
instead of in every project.

Agent #1: the smallest thing that is still an agent

Two actions and one goal. Nothing in this code says which runs first:

(require '[embabel-clj.core :as ec]
         '[embabel-clj.blackboard :as bb])

(def hello
  (ec/agent
   {:name        "hello"
    :description "looks a fact up, then writes an answer"
    :goals   [{:name "done" :pre [:answered?] :value 1.0}]
    :actions [{:name "look-up" :post [:facts?]
               :fn (fn [ctx]
                     (bb/put! ctx :facts ["Clojure is a Lisp on the JVM."])
                     (bb/set-condition! ctx :facts? true))}

              {:name "answer" :pre [:facts?] :post [:answered?]
               :fn (fn [ctx]
                     (bb/put! ctx :answer (str "Here: " (first (bb/fetch ctx :facts))))
                     (bb/set-condition! ctx :answered? true))}]}))

(ec/deploy! (:platform sys) hello)

(-> (ec/run! (:platform sys) hello {})
    (ec/result {:slots [:answer] :conditions [:answered?]}))
;; => {:status "COMPLETED"
;;     :slots {:answer "Here: Clojure is a Lisp on the JVM."}
;;     :conditions {:answered? true}}

The A* search connects three facts: to reach :answered? you need answer,
which requires :facts?, which only look-up produces. Delete the answer
action from the vector and the agent doesn't become half an agent. It has no plan
at all, and the process reports STUCK.

A word on :pre [:facts?]. Those keywords are named boolean conditions, the
other flavor from the typed one used in the Rosetta section above. Both are
first-class in the framework and both work from Clojure. Named conditions suit
derived boolean state ("is this blocked?", "do we have evidence yet?"); the typed
layer suits data flow, where each step consumes and produces domain objects. The
rest of this post uses named conditions, because the agent it follows is a state
machine over a physical process rather than a chain of transformations.

Agent #2: the order pipeline, and how modeling actually goes

The hello agent is a straight line, which hides the point of a planner. Here is
the agent from the hook, written out in full. It is the one the experiments at
the end of this post measure:

(def order
  (ec/agent
   {:name        "order"
    :description "Checks stock, picks, packs and ships an order"

    :goals   [{:name "shipped" :description "order on its way"
               :pre [:delivered?] :value 1.0}]

    :actions [{:name "check-stock" :description "checks the stock"
               :post [:checked?] :cost 0.1
               :fn (fn [ctx]
                     (bb/put! ctx :stock 9)
                     (bb/set-condition! ctx :checked? true))}

              {:name "pick" :description "picks into boxes"
               :pre [:checked?] :post [:picked?] :cost 0.2
               :fn (fn [ctx]
                     (bb/put! ctx :boxes (quot (bb/fetch ctx :stock 1) 3))
                     (bb/set-condition! ctx :picked? true))}

              {:name "pack" :description "seals the box"
               :pre [:picked?] :post [:packed?] :cost 0.2
               :fn (fn [ctx]
                     (bb/put! ctx :seal "S-77")
                     (bb/set-condition! ctx :packed? true))}

              {:name "ship" :description "hands over to the carrier"
               :pre [:packed?] :post [:delivered?] :cost 0.5
               :fn (fn [ctx]
                     (bb/put! ctx :tracking "BR-0001")
                     (bb/set-condition! ctx :delivered? true))}]}))

:cost is not decoration. When more than one action can produce what the planner
needs, A* picks by cost, which is how you express "try the cheap local lookup
before the expensive LLM call" without writing a single if.

Five modeling rules are worth stating, because each of them was learned by
getting it wrong first:

A condition never set is FALSE, not UNKNOWN. Model positive poles: ok? set true when there is no error. There is no pre = NOT x.
No : inside a condition *name*, because it triggers the determiner's data-binding branch. Namespaced keywords (:mail/verified?) are the happy path; the library's schemas reject the broken form at construction.
Worker actions need :rerun? true. The default canRerun=false injects a hasRun_<name> precondition, so the action fires once per process. Fine for a pipeline step, wrong for a retry-able worker.
Declare :post optimistically. An action should declare the goal condition it may achieve, so A* can chain to the goal; re-derive the real value at runtime. Otherwise the plan never forms.
Use a gate. Give worker actions a single positive gate (:work/unblocked?) that every remedy action optimistically posts. Without it, A* will happily retry a doomed action until the budget is gone.

And the one that saves the most time in practice: retries are fail-fast by
default in this library, one attempt. The framework's own default is 5
attempts with 10s → 60s backoff, which turns a typo in an action body into
minutes of watching nothing happen. Opt back in per action with :retries 2.

Budgets and planners, as data

Everything about how a run behaves is another map:

(ec/run! (:platform sys) order
  {:bindings {:order "P-4711"}
   :options  {:budget  {:cost 2.0 :actions 40 :tokens 200000}
              :planner :goap
              :verbosity {:show-planning true}}})

:budget is worth understanding rather than just setting: it is three
early-termination policies composed together (max actions, max tokens, hard
budget limit). Which is why adding your own doesn't replace it:
:early-termination composes.

{:options {:budget {:cost 0.10}
           :early-termination [(fn [proc] (when (good-enough? proc) "close enough"))]}}

nil means carry on; a string is the reason it stopped.

Agent #3: lazy conditions, the `@Condition` equivalent

Named conditions that actions set have a stale-state window: the value is
whatever was last written. The framework's answer is @Condition, a function the
planner calls on demand, during world-state determination. From Clojure it is
another entry in the map:

(def triage
  (ec/agent
   {:name "triage" :description "escalates only when evidence is thin"

    :conditions [{:name :co/needs-evidence?
                  :fn (fn [ctx]
                        (and (not (bb/condition? ctx :co/evidence-ready?))
                             (or (bb/condition? ctx :co/ambiguous?)
                                 (bb/condition? ctx :co/empty-result?))))}]

    :goals   [{:name "resolved" :pre [:co/resolved?] :value 1.0}]
    :actions [{:name "gather-more" :pre [:co/needs-evidence?] :post [:co/evidence-ready?]
               :cost 0.8 :rerun? true
               :fn (fn [ctx] …)}
              {:name "resolve" :pre [:co/evidence-ready?] :post [:co/resolved?]
               :cost 0.2
               :fn (fn [ctx] …)}]}))

:co/needs-evidence? is never set by anyone. It is a
ComputedBooleanCondition, the framework's own class, evaluated by the planner
each time it determines the world state. No :after refresh hook, no stale
window. Verified end to end: a goal whose only precondition is a lazy condition
does get achieved.

Agent #4: talking to the model, with malli on both borders

An action asks for LLM access by tagging itself :llm? true; the context it
receives then carries the handle. The interesting part is the contract with the
model:

(require '[embabel-clj.schema :as schema])

(def Insights
  [:map
   [:summary    {:description "2-3 sentence summary"} :string]
   [:biome      {:description "identified biome"} :string]
   [:confidence {:optional true :description "0.0 to 1.0"}
    [:double {:min 0.0 :max 1.0}]]])

(def naturalist
  (ec/agent
   {:name "naturalist" :description "reads a photo and reports the biome"
    :goals   [{:name "reported" :pre [:reported?] :value 1.0}]
    :actions [{:name "analyse" :post [:reported?] :llm? true
               :fn (fn [ctx]
                     (let [insights (schema/create-edn! ctx
                                     {:schema     Insights
                                      :llm        "openai/gpt-4o"
                                      :image      (bb/fetch ctx :image)
                                      :max-tokens 1200
                                      :retries    1
                                      :prompt     (schema/edn-prompt
                                                   Insights
                                                   {:preamble "You are a field naturalist."})})]
                       (bb/put! ctx :insights insights)
                       (bb/set-condition! ctx :reported? true)))}]}))

One value, Insights, does four jobs: it generates the prompt describing the
expected shape, parses the EDN the model returns, coerces the types, and on a
validation failure re-asks the model with the humanized errors included. That
last one is a self-healing loop, and it is a loop precisely because the schema is
a value the code can inspect and turn back into prose.

Two field notes that cost real money to learn:

Set :max-tokens on OpenRouter. It pre-authorizes the cap against your balance. Absent, the model's maximum output (16k for gpt-4o) is reserved, and a low-credit account gets a 402 before generating a single token.
edn-prompt only lists top-level fields. With a nested schema and a small model, the model cannot see the shape it should produce, so pass an explicit :prompt showing the exact form. The :schema keeps validating either way.

Clojure functions as tools

No @Tool annotation is needed: Embabel has had a functional tool API since
0.4.0, and the library bridges it to malli. One schema describes the arguments,
becomes the JSON Schema the model sees, and validates the call before your
function ever runs:

(require '[embabel-clj.tools :as tools])

(def freight-quote
  (tools/tool
   {:name        "freight_quote"
    :description "Quotes freight for a destination and weight."
    :schema      [:map
                  [:destination {:description "destination city"} :string]
                  [:kg          {:description "package weight in kg"} :double]]
    :fn          (fn [{:keys [destination kg]}]
                   (quote-service/price destination kg))}))

;; inside an action tagged :llm? true
(schema/ask ctx {:llm    "openai/gpt-4o-mini"
                 :tools  [freight-quote]
                 :max-tokens 200
                 :prompt "How much to ship 3.2 kg to Belo Horizonte?"})

Invalid arguments come back to the model as a readable error so it can
self-correct, and an exception in your function does not kill the plan. For
platform-provided tool groups (including MCP servers), an action declares
:tool-groups [:web].

Extension points, as functions

Embabel's extension surface is a set of small interfaces: one or two methods,
called by the framework at a known moment. In Kotlin each one is a class. In
Clojure each one is a fn, and the object the framework hands you arrives as a
plain map.

Watching a run (AgenticEventListener):

(require '[embabel-clj.events :as events])

(ec/run! platform order
  {:options {:listeners [(fn [ev] (println (:event ev) (:process-id ev)))]}})
;; :agent-process-creation         a1b2…
;; :agent-process-plan-formulated  a1b2…
;; :action-execution-start         a1b2…

;; or record the whole run in one line:
(let [[l log] (events/recording-listener)]
  (ec/run! platform order {:options {:listeners [l]}})
  (map :event @log))

Intercepting the tool loop (ToolLoopInspector, ToolLoopTransformer,
ToolCallInspector). Inspectors observe; transformers rewrite what flows
through, so the return value replaces the original and nil keeps it:

(schema/ask ctx
  {:prompt "…" :tools [freight-quote]
   :tool-loop-inspectors   [{:after-llm-call (fn [c] (log/info :usage (:usage c)))}]
   :tool-loop-transformers [{:after-tool-result
                             (fn [c] (subs (:result-as-string c)
                                           0 (min 500 (count (:result-as-string c)))))}]})

A typo like :after-tool-results is a closed-schema error at construction, not a
hook that silently never fires. All three interfaces were verified with javap
against 0.4.0, 0.5.0 and 1.0.0. This is not new 1.0 surface; it was never bridged
to Clojure.

Guarding the borders (UserInputGuardRail, AssistantMessageGuardRail). A
guardrail is a validator with a name, and a malli schema already is exactly that,
so the schema can be the guard:

(schema/ask ctx
  {:prompt "…"
   :guardrails [{:on :user-input :name "no-secrets"
                 :fn (fn [{:keys [content]}]
                       (when (re-find #"sk-[A-Za-z0-9]{20,}" content)
                         "the prompt contains what looks like an API key"))}
                (gr/assistant-message {:name "length" :schema [:string {:max 4000}]})]})

Your fn returns a verdict in whatever shape is natural: nil/true passes, a
string is one violation, a vector several, a map carries :code and :severity.

[!note] Severity is what decides
Only :critical aborts the call (GuardRailViolationException); :error,
:warning and :info log and let the call through. Enforcement keys on the
severity of the errors, so a verdict carrying no errors has nothing to act
on. The library never produces one: a bare {:valid? false} is materialized as
a critical violation, which is also why :critical is the default severity
here.

Stopping. Three kinds, and they are genuinely different. The platform
deciding from outside, once per tick (:early-termination); the planner failing
to reach any goal (:stuck-handler); and the cooperative kind, where the
action body itself says it is done:

(require '[embabel-clj.termination :as term])

;; the stuck handler resolves by side effect — AgentProcess IS a Blackboard
{:stuck-handler (fn [proc]
                  (bb/set-condition! proc :fallback/ok? true)
                  "opened the fallback path")}      ; => REPLAN

;; cooperative, from inside an action
(term/terminate-agent! ctx "found what we came for")

None of this makes your project import com.embabel.

Durable history, and a process that survives its JVM

An Embabel process already carries its own log. AgentProcess.history
exists, and the framework calls update(this) on the AgentProcessRepository on
every tick: two ready-made hooks, in the right place. The default repository
keeps everything in memory, which is the sensible default for development, and
replacing it is a declared extension point.

That is what embabel-clj.process-store does. A decorating repository delegates
the live object and, on every save/update, projects the process into EDN and
appends a record to a log. The object stays ephemeral; the history becomes
queryable data.

(require '[embabel-clj.process-store :as ps])

(def repo (ps/edn-repository {:file "target/processes.edn"}))
(platform/start! {:initializers [(ps/as-primary-bean repo)]})

;; later, including from another JVM, with the first one long dead:
(def log (ps/read-log "target/processes.edn"))
(ps/summary  log)                          ; => {:records 128 :processes 7 :cost 0.0142 …}
(ps/runs     log)                          ; => one row per process
(ps/timeline log "a1b2…")                  ; => that process's trajectory
(ps/as-of    log "2026-07-30T18:00:00Z")   ; => what the system knew at 18:00

Two things had to be right for that to work, and both are worth knowing if you
ever swap a framework bean:

The bean must go in as @Primary, because Embabel's @Bean agentProcessRepository is unconditional. A plain registerSingleton creates a second candidate of the same type and Spring raises NoUniqueBeanDefinitionException.
AgentProcess refuses to serialize. It is annotated @JsonSerialize(using = ComputerSaysNoSerializer::class), so persisting it means projecting field by field, not handing it to an ObjectMapper.

And the honest boundary, stated up front: this makes the history durable.
Making the process resumable is a further step, and its price is a domain
discipline, only values go on the blackboard. Anything that is not a value
comes back as a tombstone marking exactly where the discipline broke.

What the measurements say

Claims here come with numbers, and the experiments were written so they could
come out negative. Five live in the repo and run offline, with no LLM key, no
Docker and no Neo4j. Everything below is the median of three consecutive runs
on the same machine, and where a figure moved between runs it is given as a
range rather than as a single number:

	Question	Result
E1	Is a process resumable, or only its history durable?	Resumable, identically in all three runs. Phase 1 calls `System/exit 9` inside the third action: real JVM death, no `finally`, no shutdown hook. Phase 2 is a different OS process. It reads the log, restores blackboard and conditions, and runs `["pack" "ship"]`, not the two already done, to `COMPLETED`, with 0 tombstones.
E2	What does keeping the log cost?	~0.25 ms/tick (0.244–0.269 across runs) and ~5,250 B/process, over 1500 runs. Measured on an agent with no LLM, where a tick lasts microseconds: the worst possible case for the log. On a tick that calls a model, it disappears into the noise.
E3	How much of an agent is really data?	93.1%, byte-identical in all three runs. 626 bytes of EDN read in another JVM: 58 leaves, 54 data, 4 code references. Deleting an action in the file makes the goal unreachable; changing one precondition reroutes the plan.
E4	Does a log-derived cache save tokens?	Yes, 100%, with a label. See below.
E5	Can the log alone drive an LLM judge?	Yes. 40 runs, half with a planted routing bug invisible in the results (all 40 orders delivered, all `COMPLETED`) and visible only in the path. Recall and precision were 1.0 in all three runs, with 0 false positives: 9/9 detectable bugs caught in the first, 12/12 in the other two.

Three of these have a caveat, and in each case the caveat is the finding.

E1's ceiling. The resumed process is a new process, with a new id and a
history starting from zero. What continues is the world, not the identity.
Stitching the two timelines together is the next step, and it is a small one.

E4 is the one to read carefully, and running it three times made the point
better than one run could. Without the cache the agent genuinely oscillates on
the same input: the original path came up 11, 11 and 4 times out of 20 across the
three runs. With the cache: 20/20 identical and zero calls, every time. So the
cache does not fail under non-determinism. It erases it. The agent stops
deciding and starts replaying a recorded decision, silently. That makes
log-derived replay excellent for audit and regression testing (it pins the path
on purpose) and unsafe as transparent memoisation anywhere the model chooses
the branch. Without the control arm the experiment would have lied: 20/20
identical paths reads as a stable agent, when it was the cache pinning the route.

E5's methodological note. Of the 20 buggy agents only 9 to 12 were detectable
at all, depending on the run, because when the agent classifies "simple" the bug
and the correct behavior coincide. The judge caught every detectable one in all
three runs. Evaluation measures what the trace exposes, not what you intended.

Honest limits

The interop tax is real. It is paid once, inside the library, but it is paid. Roughly fifteen Kotlin-interop gotchas had to be found by hitting them: value classes with hyphenated mangled members reachable only through java.lang.reflect; @JvmStatic val compiling to a method, not a field; Kotlin data classes with non-null defaults that must be constructed through the synthetic bit-mask constructor.
6.9% of the agent is not data, and no format changes that. A spec can name a behavior; it cannot contain it.
The library does not expose everything as data yet. Cost tracking aggregation, streaming and thinking, closed/open execution modes and explicit domainTypes registration are still in the queue. The framework offers them; the Clojure bridge is what does not exist yet.
The library is experimental, and it is one person's. The framework is production-grade; this is a bet on a representation.

Running it yourself

Everything in this post is in
github.com/raidenario/embabel-clj,
Apache-2.0, the same licence as Embabel.

The five experiments run offline, with no LLM key and no Docker:

git clone https://github.com/raidenario/embabel-clj
cd embabel-clj/experiments && ./run-all.sh

The agents in this post live under examples/, and hello starts with a key
from any OpenAI-compatible provider. The quickest read of what the library does
is nature: one namespace, zero interop, a photo in and validated EDN out.

Quoting Difficulties

Paula Gearon — Mon, 17 Aug 2026 21:13:20 +0000

In my last post I discussed DSLs for database querying in Clojure. These typically take the form of data structures.

I also discussed how some query languages, like SPARQL and Datomic, use variables in their queries, and that these appear in Clojure as symbols. That post also demonstrated using quoting to embed symbols easily into a structure, and unquoting to use values inside those same structures.

Some of it got messy.

Symbol Reuse

A colleague was recently trying to build SPARQL queries using Flint. This is a library that allows SPARQL queries that look very similar to Datomic queries.

He was trying to programmatically build query fragments that could be appended to each other to form a complete query. Each fragment was generated by functions that returned a small structure that could be added into the query.

In most cases, he could use quoting to return his structure. For instance, the following fragment might be used to find the name of a person who had changed an entity:

[[entity :data/modifiedBy ?person] [?person :data/firstName ?name]]

This is not the final form though, since he wanted to both pass in a value for entity, while also quoting the symbols in his structure.

Using the techniques from the last post, this is relatively straightforward:

(defn modifier-name
 [entity]
 [[entity :data/modifiedBy '?person]
  ['?person :data/firstName '?name]])

However, there are occasions where the entity might be modified more than once, and so multiple names should be returned. This will need a configurable name variable:

(defn modifier-name
 [entity name-var]
 [[entity :data/modifiedBy '?person]
  ['?person :data/firstName name-var]])

This would let a developer call something like:

(concat (modifier-name '?entity '?name1) (modifier-name '?entity '?name2))

(note: There are overlaps between what ?name1 and ?name2 will bind to. This is just for illustration.)

Autogensym

Unfortunately, this has a bug. In both cases, the ?person variable is used, meaning that both ?name1 and ?name2 will always be bound to the same values. One way to address this is to generate a new symbol for the query.

Since we're been using quoting, then a common way to generate symbols is to use a syntactic feature called an autogensym inside a quote. This uses a symbol name with a trailing # character:

(defn modifier-name
 [entity name-var]
 `[[~entity :data/modifiedBy ?person#]
   [?person# :data/firstName ~name-var]])

This version is using syntax quoting, and embedding entity and name-var, as discussed in the previous post.

However, this version has a bug too. The appearance of ?person# in the code tells the Clojure reader to generate a new symbol.

user=> (modifier-name '?entity '?name)
[[?entity :data/modifiedBy ?person__2__auto__]
 [?person__2__auto__ :data/firstName ?name1]]

Each new use of this ?person# expression (in a new context) should result in a new symbol. However, this symbol gets reused when the function gets called again.

user=> (concat (modifier-name '?entity '?name1)
               (modifier-name '?entity '?name2))
([?entity :data/modifiedBy ?person__2__auto__]
 [?person__2__auto__ :data/firstName ?name1]
 [?entity :data/modifiedBy ?person__2__auto__]
 [?person__2__auto__ :data/firstName ?name2])

The symbol ?person__2__auto__ was returned from both calls, because the generation actually occurred when the function was read, not when it was executed.

This is the same issue that was discussed in an Ask Clojure Question. Syntax quoting and autogensyms are most often used in macros, and the scope of a generated value is typically restricted so that any generated symbols cannot interact with each other. The case discussed in that Clojure question was when a macro was recursive. In that case, the symbols generated during recursion were all the same, since they all shared scope.

Our query is not using recursion, but instead it is capturing the name of this symbol and returning it to the calling scope. This means that the scope of the generated name is extended to the calling context, allowing it to interfere with other generated names in that context. i.e. the scope "escaped".

In other words, despite autogensyms being common when quoting expressions (most commonly in macros), they are not appropriate for anything that can escape the current context.

Addressing the issue

One solution to this is to generate a symbol on each execution of the function. This can be done manually, rather than using the autogensym syntax:

(defn modifier-name
 [entity name-var]
 (let [?person (gensym "?person")]
   [[entity :data/modifiedBy ?person]
    [?person :data/firstName name-var]])

This creates a new value every time.

Recap

Using functions to generate fragments of queries can result in conflicting fragments, particularly in graph languages that have variables in their syntax. In these cases, a new variable is needed for each fragment.

Clojure has a facility for creating new variable names easily, called "autogensym". However, the new name is only generated when the code is read, meaning that any function using this construct will always return the same symbol. "Autogensym" can be helpful, but only if the context of the generated symbol can never overlap with the context of another call to the same autogensym.

Query Mess

In the first post I mentioned that macros can simplify a query DSL. The next post will demonstrate this.

Clojure Query DSLs

Paula Gearon — Mon, 17 Aug 2026 20:11:03 +0000

Domain Specific Languages (DSLs) are a popular technique for writing database queries. There are a few reasons for this, including:

They help ensure queries are syntactically correct
They make programmatic construction of queries more tractable
Fragments of queries are easier to reuse

Some languages implement DSLs in libraries, some allow the language to be extended to include the DSL, and some can use already existing syntax and data structures to implement the DSL. While most languages can implement DSLs in libraries, Clojure also has the option of extending the language via macros, as well as providing syntax for regular data structure that can also be convenient to use.

Macros

While basic macros are relatively easy to write in Clojure, they can become quite complex. In general, when it comes to Clojure macros, I think Sandra Sierra's 2010 advice holds up well: You do not write macros.

That said, some libraries may use macros to make writing queries easier for developers. This can make it easier to incorporate names and labels into expressions that would otherwise lead to errors on "unbound" values. Many Clojure DSL libraries eschew this, since keywords often work just as well. As an example, a SELECT expression for reading the name and age columns of a table would need a macro if a developer wanted to write:

(select name age)

However, the complexity of a macros can be avoided by switching to keywords instead:

(select :name :age)

Structures

Clojure code is almost always written to use the regular data structures that are built into the syntax of the language. These are:

Maps: {key value …} Also called a "Dictionary" in languages like Python.
Sets: #{data …}
Vectors: [data …] Called "Lists" in Python.
Lists: (data …) Implemented as Linked Lists.

Lists are a little different, as they are "executed" by defautl in Lisp dialect like Clojure. This is avoided by introducing the list with a ' quote character. e.g. '(1 2 3)

Since these structures are part of the language, they can be a simple way to build a DSL for querying. For instance, Sean Corfield's HoneySQL can represent an SQL query using a map and vectors:

{:select [:a :b :c]
 :from   [:foo]
 :where  [:= :foo.a "baz"]}

Datomic does something similar, using either a map or a vector for the queries:

'[:find ?title 
  :where [?e :movie/title ?title] 
         [?e :movie/release-year 1985]]

There is an issue here though. Unlike previous examples, this last query is using variables (marked with a ? prefix) as a part of the query language. This is especially common in graph languages like Datomic or SPARQL.

Quoting

Using a : to turn these variables into keywords makes it harder to distinguish variables from actual values stored in the database (since Datomic stores keywords directly, and SPARQL libraries assume keywords to be CURIEs). Instead, Clojure Symbols are used. The problem is that symbols are the mechanism that Clojure uses for associating data with a name, so using a symbol usually results in Clojure looking for that data, which will be an error if the symbol is not bound, and inserts a value where you wanted a variable if it is found. This is avoided using the ' quote character.

To illustrate this, let's look at that Datomic query again, this time without the quote. I'll show what happens at a REPL (the Clojure prompt), where the prompt includes the current namespace (user by default, though it can be something else):

user=> [:find ?title 
        :where [?e :movie/title ?title] 
               [?e :movie/release-year 1985]]
Syntax error compiling at (REPL:0:0).
Unable to resolve symbol: ?title in this context

user=> (def ?title "not a variable")
user=> (def ?e "also not a variable")
user=> [:find ?title 
        :where [?e :movie/title ?title] 
               [?e :movie/release-year 1985]]
[:find "not a variable" :where ["also not a variable" :movie/title "not a variable"] ["also not a variable" :movie/release-year 1985]]

This is read, but we can see that the use of the symbols has placed their saved values into the query, rather than a variable like we wanted.

We can avoid this problem by quoting the symbols that we want to keep as symbols:

user=> [:find '?title 
        :where ['?e :movie/title '?title] 
               ['?e :movie/release-year 1985]]
[:find '?title :where ['?e :movie/title '?title] ['?e :movie/release-year 1985]]

We can also quote entire structures that contain multiple variables:

user=> '[:find ?title 
         :where [?e :movie/title ?title] 
                [?e :movie/release-year 1985]]
[:find ?title :where [?e :movie/title ?title] [?e :movie/release-year 1985]]

Note that the result is printing the data structure, and not trying to evaluate it. Because of this, the symbols are not printed with a quote.

Mixed Symbols

Quoting entire structures makes it easy to include multiple symbols, but it also makes it hard to include values from a program. For instance, a user may be asking to get all titles from a year that they provide in a user-interface:

user=> (let [release-year (get-user-input)] ;; user input 1985
         '[:find ?title 
           :where [?e :movie/title ?title] 
                  [?e :movie/release-year release-year]])
[:find ?title :where [?e :movie/title ?title] [?e :movie/release-year release-year]]

That's put a symbol into the query when we wanted a number associated with that symbol.

There are lots of ways to address this. One is to only quote the parts we need to:

user=> (let [release-year (get-user-input)] ;; user input 1985
         [:find '?title 
          :where '[?e :movie/title ?title] 
                  ['?e :movie/release-year release-year]])
[:find ?title :where [?e :movie/title ?title] [?e :movie/release-year 1985]]

This works, but it can (and frequently does, at least in my code) lead to lots of quote characters everywhere, which can be a bit bug prone too (LLMs will usually catch it, but I'm here to discuss how WE write code, not LLMs).

Another way is to bind the names to symbols (binding to a symbol with the same name would reduce confusion):

(let [release-year (get-user-input)  ;; user input 1985
      ?e (symbol "?e")
      ?title (symbol "?title")]
   [:find ?title 
    :where [?e :movie/title ?title] 
           [?e :movie/release-year release-year]])

But now we're asking the developer to increase their code significantly. That's not really helpful.

For completeness, I'll also mention that sometimes it works to build the parts you need, and create the query structure with code:

(let [release-year (get-user-input)]  ;; user input 1985
   (conj '[:find ?title :where [?e :movie/title ?title]]
          ['?e :movie/release-year release-year]])

This is sometimes useful, but is too cumbersome for basic querying.

Unquoting

Another option is the "unquote". This tells the Clojure reader that is reading quoted data that the next item is not to be considered as quoted. This is done with the ~ character. However, it does not work quite as you might expect.

For simplicity, I will reduce the evaluation to just the last part:

user=> (def release-year 1985)
user=> '[?e :movie/release-year ~release-year]
[?e :movie/release-year (clojure.core/unquote release-year)]

Unfortunately, this has shown us what the ~ unquoting gets translated to. Quoting actually gets translated like that too. We just haven't seen it before:

user=> '['?e :movie/release-year ~release-year]
[(quote ?e) :movie/release-year (clojure.core/unquote release-year)]

Instead, we need to use a different kind of quoting: syntax quoting. This is done with a single "back-quote" or .clojure user=> (def release-year 1985) user=> `[?e :movie/release-year ~release-year] [user/?e :movie/release-year 1985]This embedded the value ofrelease-yearas we wanted, but it has also change the?esymbol. Now it tells us that it's the the symbol?ein the namespaceuser`. That's the current namespace, so that's correct, but we want to embed the symbol without the namespace.

This is a tricky form. We want to "unquote" from the syntax-quote, but then we want to immediately "quote" again:
clojure user=>[~'?e :movie/release-year ~release-year]
[?e :movie/release-year 1985]
`

Going back to the complete query, we can see the full form:
clojure (let [release-year (get-user-input)] ;; user input 1985 [:find '?title :where '[?e :movie/title ?title][~'?e :movie/release-year ~release-year]])
`

This is not entirely satisfactory, and it explains why macros may be attractive, but it does show an approach.

Wrap Up

This post demonstrates some of the approaches of using Domain Specific Languages (DSLs) in Clojure, focusing on data structures to represent database queries. Query languages like Datomic and SPARQL use symbols in their queries, and we looked at a few ways that these can be embedded into a query structure.

Clojure vars - notes

ivan.gavlik — Sun, 26 Jul 2026 17:14:06 +0000

Intro

named references (symbol) to values of fn
they live in a namespace
mutable reference to an immutable value

Var is separate from the value so you can redefine it

Note: symbol is just name

Dig Deeper

Functions are actually stored in vars

(defn greet [name] (str "hello" name))
; is equal to 
(def greet (fn [name] (str "hello" name)))
; because defn is macro

Dynamic vars

Allows temporary thread-local bindings

(def ^:dynamic *debug* false)

; temporarily change it
(binding [*debug* true]
 (prinlnt *debug*))

Metadata

(def ^{:doc "A counter"} counter 0)

Symbol vs Var

Symbol

Pice of code that names something

(type 'x)
;; => clojure.lang.Symbol

Writen as 'x
Exists in code and data

Var

Runtime object that point to immutable value
Written as #'x or (var x)
Exists at runtime

Symbol ──▶ Var ──▶ Value
x ──▶ #'user/x ──▶ 42

Example explained

(def x 43)
x
; 43

In the code

find the symbol
resolve it to var #'user/x
dereference var
produce 42

Dig Deeper

Note symbol can refere to local binding (not a Var) or local variable

; local binding
(let [x 10]
  x)

; local variable
(fn [x] x)

Immutability

Vars are mutable
The values they point are (usually immutable)

The var can change what it points to the data/vale cannot change

Imagine a program without vars
we have immutable values but no way to give them names

Vars and namespaces

Namespace is mapping from symbols to vars
Namespace is object that contains vars

(ns math)
; internaly
; pi --> var
; inc --> var

Referring to another namespace

(ns animals)
(def dog "Labrador")

(ns zoo
  (:require [animals]))

animals/dog ;; 


(ns zoo-2
  (:require [animals :as a])) ; aliases

a/dog ; shorthand for animals/dog


(ns zoo-2
  (:require [animals :refer [dog]])) ; refering vars

dog ; shorthland for a/dog

Dereferencing

Var fully qualified name includes namespace: math/pi or user/x

Example

(def x 42)

When evaluating steps

find var
deref var
42

you can also do dereferencing by:

@#'x 
; or
(deref #'x)

Evaluation pipeline simplify

Examples

(double-it x)

Soruce code contains symbols (double-it x)
Symbols is name ('x, it has type clojure.lang.Symbol)
Compiler resolve namespace
What does the symbol x refer to in the current namespace
So we get namespace-name/x var
Note: namespace dosen't store values it stores vars
Var is runtime object so it dereferences it to get values
Invocation (of the function or the value)

Why we have vars, what not directly have values, because with vars we have

redefintion (REPL)
metadata
dynaming binding

Dig Deeper

Special Symbols

' — Quote

Dont evaluate this treat it as data

Example

(def x 42)

This means

Resolve symbol
Find the var
Return it value

'x
; => x

This means

Return symbol

#' — Var Quote

Resolve this symbol to its Var

Example

(def x 42)
#'x
;; => #'user/x

The result is not 42
the result is the Var object
To get a value you can dereference it using @

@#'x
;; => 42
; or

(deref #'x)

When to use it

Metadata is attached to the Var
Testing and mocking
Implementing macros
Dynamic Vars and advanced runtime features

Advent of Code 2015 days 3-8 in Clojure

Andy N — Wed, 27 May 2026 15:42:57 +0000

Yeah, I'm starting to think my initial comment about taking until the heat death of the universe to complete this wasn't far off the mark. I'm not really slow at finishing the tasks, it's just between working , the drudgery of everything else in life and possible undiagnosed ADHD, progress becomes a sporadic thing. Gone forever I think are the late-nighters of chugging caffeinated drinks...

But with that said, I have been slowly chugging away and gotten myself up to the heady heights of puzzle number 8.

I don't think I shall labour over each and every puzzle, instead I'll just gloss over the interesting parts.

Day 03

You're trying to determine how many points are visited if you're given a list of directions (N/S/E/W effectively). One pattern with this sort of thing I like to do is to store the position transformation as a map with the keys being the direction and the values being values to add to x and y coordinates.

(def moves {\^ [0  1]
            \v [0 -1]
            \> [1  0]
            \< [-1 0]})

The rest is just bookkeeping ;D

Day 04

Trying to mine a proprietary cryptocoin. I just used Java interop here - (java.security.MessageDigest/getInstance "MD5"). It is then a matter of looping through numbers to get the required number of leading zeros in the hexadecimal representation of the digest.

This was pretty brute-force and I don't expect to retire from crypto riches any time soon. It's quite slow too - clearly the hashing is going to be but I suspect we could possibly run multiple threads in parallel and/or optimise the way we're creating the byte-array to feed into Java each loop.

As it is, I was content just to wait for it to finish...

Day 05

String parsing really. I'm not a massive fan!

Was nice going back to see part of my original solution looks like this;

(defn nice?
  "is a word nice?"
  [word]
  (and (has-three-vowels? word)
       (has-repeated-letter? word)
       (no-forbidden-strings? word)))

Pretty legible. I guess you'd write something similar in most languages, but the convention of adding a question mark to tests is a nice touch.

Day 06

Mapping text instructions into turning a series of lights on/off/toggling in a given rectangle. Nothing to write about but I was interested to see if anyone had plotted the result in case there was a picture.

There isn't.

Day 07

Ah, we're getting interesting now, we had to simulate a basic logic circuit. We're given a input like;

123 -> x
456 -> y
x AND y -> d
x OR y -> e
x LSHIFT 2 -> f
y RSHIFT 2 -> g
NOT x -> h
NOT y -> i

I suspect there's a proper way of doing this in which we create a graph of connections and evaluate everything in the proper order. But what I did was just to brute force the whole thing; just keep running through the instructions until every instruction could be executed e.g. if you imagine in the example above that the numbers aren't applied to x and y until the last line, then we couldn't perform most of it until the second loop round the instructions.

Yes, as I edit this, I'm seeing a theme forming here where my solutions are just brute forced.

Day 08

String parsing again :D Trying to count the number of characters in a string and in the final representation. Not much to say again. Slogged through it.

Parser?

So far each problem's input is basic text, but I'd be interested to see if there's a tidy way of specifying the puzzle input. For example Day 2's input looks like;

1x2x3
1x3x6
...
...

So I'm thinking we almost want a function like;


(parse-input "day02.input" "<int>x<int>x<int>")

;; -> ((1 2 3) (1 3 6) ... ...)

Usually I'd either split or use regex for input, but it seems like what I'd like is to also be able to specify the basic type. Puzzle 8's example;

London to Dublin = 464
London to Belfast = 518
Dublin to Belfast = 141

Would be;

(parse-input "day08.input" "<string> to <string> = <int>")

;; -> (("London" "Dublin" 464) ...)

Or even better!

(parse-input "day08.input" "<string:from> to <string:to> = <int:distance>")
;; -->
({:from "London" :to "Dublin" :distance 464} ...)

I'd be interested if you know of anything like this feature.

End

I'll carry on with some more problems. I don't think I'll be entering any leaderboards soon ... unless there are some for slowest?

Confidence Is Not Ownership

Kingsley Onoh — Wed, 06 May 2026 16:00:28 +0000

What should a finance queue do when two credible records point at the same case?

An invoice discrepancy and a contract breach can describe the same dispute. They can also describe two different disputes with the same counterparty, the same currency, and nearly the same amount. That is the trap in a finance operations queue. The data looks related before anyone has proved ownership.

The Workbench ingests exceptions from invoice reconciliation, transaction reconciliation, contract lifecycle events, webhook dead letters, manual operator entry, and signed Hub fanout. Every source carries its own identifiers. Some are reliable. Some are only reliable inside the upstream tool that produced them.

I had to decide what the system should do when a new exception looks like it belongs to an existing dispute.

The tempting version is simple: compute a score, pick the highest dispute, attach the exception. That makes demos feel clean. Exceptions flow in, disputes become richer, and the queue stays small.

It is also how a finance system quietly corrupts its own audit trail.

Once an exception is attached to a dispute, every later action inherits that fact. SLA timers, resolution playbooks, Notification Hub events, audit PDF exports, and operator comments all treat the relationship as true. If the relationship was only probable, the system has converted probability into evidence.

That conversion is the real design problem.

The Scoring Shape

The correlator in src/drw/domain/correlator.clj uses seven signals. Source reference and entity id each carry 0.15. Counterparty carries 0.25. Currency carries 0.10. Amount carries 0.15. Date carries 0.10. Category carries 0.10.

Those weights are not magic in the sense of being secret. They are visible because this is a spec project. But the structure matters more than the numbers.

Counterparty is the gate. A candidate dispute is not eligible unless it belongs to the same tenant, is not terminal, has the same counterparty, and falls within the correlation window. Only then does scoring begin.

That means the correlator is not a general similarity search. It is a tenant-scoped dispute ownership test.

The amount signal has a 10 percent tolerance and only scores when the currency also matches. The date signal checks whether the exception was observed within 72 hours of the dispute creation time. The source reference and entity id signals compare against exceptions already attached to the candidate dispute, not just fields on the dispute itself.

That last part matters. A dispute becomes easier to recognize as it accumulates evidence. The first invoice mismatch may create the dispute. A later webhook dead letter with the same upstream reference can now match the attached evidence, even if the dispute record itself does not carry that reference.

The core function is plain Clojure:

(defn score-candidates
  ([tenant-id exception disputes attached]
   (score-candidates tenant-id exception disputes attached {}))
  ([tenant-id exception disputes attached opts]
   (let [cfg (merge default-config opts)
         review (get-in cfg [:thresholds :review])]
     (->> disputes
          (map-indexed vector)
          (filter (fn [[_ dispute]]
                    (candidate-eligible? tenant-id exception dispute cfg)))
          (map (fn [[idx dispute]]
                 (assoc (score-candidate tenant-id exception dispute attached cfg)
                        :sort-index idx)))
          (filter #(>= (:score %) review))
          (sort-by (juxt (comp - :score) :sort-index))
          (mapv #(dissoc % :sort-index))))))

There are two details in that function I care about.

First, eligibility happens before scoring. A cross-tenant dispute receives no score. A terminal dispute receives no score. A different counterparty receives no score. The function does not let a high amount or date match compensate for a broken boundary.

Second, ties preserve input order through :sort-index. That is not glamorous. It prevents unstable review queues where two equal candidates swap positions between renders and make operators think the system changed its mind.

What I Was Wrong About

I initially treated the correlation score as the hard part.

It was not. The harder question was what the system does with the score.

There are three possible outcomes in src/drw/domain/exceptions.clj. If no candidate passes review, the exception creates a new dispute and attaches immediately. If the best candidate hits the auto-merge band and auto-merge is explicitly enabled, the exception attaches and records an auto-merged correlation. Otherwise, the system creates pending correlation records and emits a dispute.correlation_pending event.

That middle branch is intentionally hard to reach. The .env.example values set AUTO_MERGE_THRESHOLD=0.92 and REVIEW_THRESHOLD=0.70, while the source correlator defaults are lower for unit-level behavior. The runtime config is stricter because this is finance operations. False attachment costs more than a larger review queue.

What surprised me is that pending correlation became a domain object, not a UI convenience.

The queue needed an id, a tenant id, an exception id, a target dispute id, a score, a rationale, a status, a decided-by user, and decision timestamps. That is a lot of structure for something that could have been a modal row.

But the moment an operator accepts or rejects a candidate, that decision becomes part of the case history. A rejected match is useful evidence. It says someone looked at the overlap and decided the exception did not belong there. If the same upstream source sends a related item later, the prior rejection explains why the system did not combine the cases earlier.

That is why correlation records live next to exceptions and disputes instead of inside a transient UI response.

The Failure Mode Hidden In Good Matches

The most dangerous false match is not a ridiculous one.

It is the match that looks reasonable.

Same counterparty. Same currency. Amount within 10 percent. Observed inside three days. Category is billing. If those signals point to the wrong open dispute, the system does not look broken. It looks efficient.

The damage appears later. A Workflow Engine playbook starts against the wrong case. A Notification Hub event tells an operator that the dispute is ready for resolution. The audit PDF now contains an exception that belongs somewhere else. Nobody sees the root mistake because every downstream artifact is internally consistent.

That is the kind of bug that worries me more than a 500 response.

A 500 stops the flow. A wrong attachment keeps moving.

The design answer was to make confidence create a decision, not mutate the dispute. A review-band candidate becomes work for an operator. The UI exposes accept and reject actions. The API carries the same boundary. The audit log records correlation creation and later decisions.

The Workbench still supports auto-merge, but it is a policy choice. It has to be enabled. The score has to clear the higher band. The code does not pretend the existence of a scoring function means the business has accepted the risk.

Why Tenant Scope Belongs Inside The Algorithm

Tenant isolation is usually discussed at the HTTP layer. API key comes in, tenant id gets attached to the request, handlers filter queries.

That is necessary, but it is not enough here.

Correlation is a cross-entity operation by nature. It compares a new exception against many existing disputes and attached exceptions. If the algorithm accepts a list that accidentally contains another tenant's disputes, the HTTP layer is already too far away to save it.

So score-candidate checks tenant equality itself. score-candidates filters candidates through candidate-eligible?, which repeats tenant, status, counterparty, and time-window checks before scoring.

This is defensive duplication with a purpose. The route should pass tenant-scoped collections. The domain should still reject anything outside the tenant boundary. In a single-tenant fixture, this looks redundant. In a two-tenant test, it is the difference between "the route behaved" and "the invariant held."

The same philosophy appears in reports. The audit PDF renderer captures a tenant snapshot, renders with strict token lookup, and the setup check renders two tenants to make sure one tenant's identity literals never appear in the other tenant's output.

The theme is the same: do not trust a boundary because a previous layer probably handled it.

The Result

The finished local build passed 160 tests with 869 assertions. The full-flow E2E drives invoice adapter polling into exception creation, assignment, investigation, Workflow Engine resolution polling, Notification Hub event capture, and audit PDF generation.

The number I care about most is smaller: the dashboard guard. It caught a practical operations failure. The first dashboard shape rendered every dispute link in the tenant fixture. The fix capped the overview at 50 open disputes and kept totals intact.

That is the Workbench in miniature. Preserve the facts. Limit the surface. Make the operator decide when the machine only has a probability.

Confidence is useful. Ownership is a human or policy decision.

bisql (Clojure Data Access Library) released v0.4.0: Support Malli Validation

fumi — Thu, 23 Apr 2026 19:54:18 +0000

Bisql

I'm building Bisql, a data access library for 2-way SQL in Clojure.

https://github.com/hatappo/bisql

Since it's “2-way,” I called it bisql with the bi- prefix.

It is pronounced like bicycle.

A common weakness of SQL-template libraries, not just 2-way SQL libraries, is that writing all SQL as templates can become tedious.

To address that, many SQL-template libraries support a query builder.

You can write some queries as templates and others with a builder.

But I think that approach is fundamentally inconsistent.

If every query function is maintained as SQL or SQL templates, the cost of reviewing and understanding the data access layer drops significantly. Every database access has a concrete representation as an actual SQL file.

Once a query builder gets mixed in, that consistency is gone.

And in practice, what starts as “we’ll only use the builder for simple queries” often drifts into using it for complex queries as well, until the generated SQL is no longer obviously what you intended.

Bisql takes a different approach:

every database access should be written as SQL.

That said, hand-writing even simple CRUD operations for every table is tedious. So Bisql takes another approach there: it generates a large and comprehensive set of typical CRUD queries automatically.

It connects to a real database, inspects the schema, considers indexes, and generates SQL templates for many index-friendly query patterns.

Then the defquery macro converts all of those .sql template files into Clojure functions at once.

So you keep the consistency of SQL-first development without the repetitive CRUD work.

Malli Support

In this release, generated SQL templates can now include :malli/in and :malli/out declaration metadata.

These hold schemas for:

the parameters passed to a query function
the response data returned from the query

Bisql SQL templates can already carry arbitrary metadata that becomes metadata on the generated query functions. Malli support builds on that.

If a query function has :malli/in and :malli/out metadata, Bisql can automatically run Malli validation during query execution. This behavior is configurable.

Bisql also generates a base Malli schema file for each table as schema.clj.

The :malli/in and :malli/out metadata refer to those generated schemas.

Example of a generated query

/*:name crud.get-by-id */
/*:cardinality :one */
/*:malli/in [:map {:closed true} [:id int?]] */
/*:malli/out [:maybe sql.postgresql.public.users.schema/row] */
SELECT *
FROM users
WHERE id = /*$id*/1

Example of a generated schema

(ns sql.postgresql.public.users.schema
  (:refer-clojure :exclude [update])
  (:require [bisql.schema :as bisql.schema]))

#_{:clojure-lsp/ignore [:clojure-lsp/unused-public-var]}
(def insert
  [:map
   {:closed true}
   [:id [:or int? bisql.schema/malli-default-sentinel]]
   [:email string?]
   [:display-name string?]
   [:status [:or string? bisql.schema/malli-default-sentinel]]
   [:created-at [:or [:fn bisql.schema/offset-date-time?] bisql.schema/malli-default-sentinel]]])

#_{:clojure-lsp/ignore [:clojure-lsp/unused-public-var]}
(def update
  (bisql.schema/malli-map-all-entries-optional insert))

#_{:clojure-lsp/ignore [:clojure-lsp/unused-public-var]}
(def row
  (bisql.schema/malli-map-all-entries-strip-default-sentinel insert))

In other words, typical CRUD queries and their schemas can now be generated automatically, and validation can run transparently with very little manual work.

A Small Expression Language for `if`

This release also adds a small expression language for if conditions inside SQL templates.

That makes conditional rendering more expressive without leaving SQL templates or introducing a separate query builder layer.

Leiningen — Complete Tutorial & Best Practices

ivan.gavlik — Sun, 12 Apr 2026 11:23:33 +0000

Leiningen is the build tool and project manager for Clojure. Think of it
like npm (Node), Maven (Java), or pip (Python) — but designed around
Clojure's philosophy.

What Leiningen Does

Creates and scaffolds projects
Manages dependencies (from Clojars + Maven Central)
Runs REPLs, tests, and builds
Compiles and packages your app (JAR/uberjar)
Runs custom tasks via plugins
Manages profiles (dev/test/prod configs)

Project Structure
my-app/
├── project.clj ← The heart: dependencies, config, build
├── src/
│ └── my_app/
│ └── core.clj ← Main namespace (note: _ not - in folders)
├── test/
│ └── my_app/
│ └── core_test.clj
├── resources/ ← Static files, config, assets
├── target/ ← Compiled output (git-ignore this)
└── README.md

Note: Clojure namespaces use - (hyphens), but folder/file names use _ (underscores). my-app.core → src/my_app/core.clj

project.clj

  (defproject my-app "0.1.0-SNAPSHOT"
    :description "What this project does"
    :url "https://github.com/you/my-app"
    :license {:name "MIT"}

    ;; Dependencies: [group/artifact "version"]
    :dependencies [[org.clojure/clojure "1.12.0"]
                   [ring/ring-core "1.12.0"]
                   [hiccup "2.0.0-RC3"]]

    ;; Entry point for `lein run`
    :main my-app.core

    ;; Source paths
    :source-paths ["src"]
    :test-paths   ["test"]
    :resource-paths ["resources"]

    ;; AOT compile specific namespaces (needed for uberjar)
    :aot [my-app.core]

    ;; Profiles: override config per environment
    :profiles
    {:dev  {:dependencies [[ring/ring-mock "0.4.0"]]}
     :prod {:aot :all}
     :uberjar {:aot :all :omit-source true}})

Real world Example

Shows how do declare dependencies, plugins on project, profiles and aliases

(defproject ebp-be "0.1.0-SNAPSHOT"
  :description "Backend project for Event Booking Platform."
  :url "https://github.com/IvanGavlik/ebp"
  :license {:name "MIT"}

  :dependencies [[org.clojure/clojure "1.11.3"]
                 [ring/ring-core "1.12.1"]
                 [ring/ring-jetty-adapter "1.12.1"]
                 [ring/ring-json "0.5.1"]
                 [compojure "1.7.1"]]

  ;; project level plugins
  :plugins [[lein-ring "0.12.6"]
            [lein-shell "0.5.0"]]

  ;; lein-ring plugin config - points to handler
  :ring {:handler ebp.handler/app
         :port 3000
         :auto-reload? true
         :reload-paths ["src"]
         :init ebp.handler/app-init
         :destroy ebp.handler/app-destroy
         :open-browser? true
         :war {:name "ebp-be"}}

  ;; entry point
  :main ebp.core

  :source-paths ["src"]
  :test-paths ["test"]
  :resource-paths ["resources"]

  :uberjar-name "ebp-be.jar"
  :profiles {:dev {:dependencies [[ring/ring-mock "0.6.2"]]
                   :plugins [[lein-ancient "0.7.0"]
                             [lein-cljfmt "0.9.2"]
                             [lein-kibit "0.1.11"]
                             [jonase/eastwood "1.4.3"]
                             [com.jakemccrary/lein-test-refresh "0.26.0"]]
                   ;; lein-ancient plugin config
                   :ancient {:check-clojure? true
                             :allow-snapshots? false
                             :allow-qualified? false}
                   :cljfmt {:indentation? true
                            :remove-trailing-whitespace? true
                            :insert-missing-whitespace? true
                            :remove-surrounding-whitespace? true}
                   :eastwood {:linters [:all]}
                   :test-refresh {:changes-only false}}
             ;; production build
             :uberjar {:aot :all :omit-source true}}
  :aliases {"dev" ["do"
                   ["shell" "cmd" "/c" "start" "cmd" "/k" "lein" "with-profile"
                    "dev" "ring" "server-headless"]
                   ["shell" "cmd" "/c" "start" "cmd" "/k" "lein" "with-profile"
                    "dev" "test-refresh"]
                   ["with-profile" "dev" "repl"]]
            "code-quality" ["with-profile" "dev" "do"
                            "cljfmt"  "fix,"
                            "eastwood,"
                            "kibit,"
                            "test,"
                            ;"ancient" ":all" ":profiles" does not work on windows
                            ]
            "ci"      ["do"
                       "clean,"
                       "cljfmt"  "check,"
                       "eastwood,"
                       "test,"
                       "uberjar"]})

Full source code here

Explanation of each of the sections

Profiles

You can put inside a profile almost anything that goes in project.clj at the top level:

  :profiles
  {:dev
    {:dependencies   [...]   ; extra deps for this profile
     :plugins        [...]   ; extra plugins
     :source-paths   [...]   ; extra source dirs
     :resource-paths [...]   ; extra resource dirs
     :env            {...]   ; env vars (needs lein-environ)
     :jvm-opts       [...]   ; JVM flags
     :main           ...     ; override entry point
     :aot            [...]}} ; override AOT

Activate a profile:
lein with-profile prod run
lein with-profile dev,test test # multiple profiles

Profiles merge, with later ones winning. :dev is active by default in most commands.

Common Patterns

Separate DB per environment

  :profiles
  {:dev  {:env {:db "jdbc:postgresql://localhost/app_dev"}}
   :test {:env {:db "jdbc:postgresql://localhost/app_test"}}}

Dev-only tools that don't ship

  :profiles
  {:dev {:dependencies [[clj-reload "0.7.0"]
                        [eftest "0.6.0"]]
         :plugins [[lein-cljfmt "0.9.2"]]}}

Different JVM memory per task

  :profiles
  {:dev     {:jvm-opts ["-Xmx512m"]}
   :uberjar {:jvm-opts ["-Xmx2g" "-server"]}}

Extra source dir for dev utilities

  :profiles
  {:dev {:source-paths ["dev"]}}

dev/user.clj — good place for REPL helper functions and startup code.

Plugins

Plugins extend what lein can do.

Where to Put Them

Global — your personal machine only
Good for personal tools you want in every project.

  ;; ~/.lein/profiles.clj  (not in the project repo)
  {:user
    {:plugins [[lein-ancient "0.7.0"]
               [lein-pprint "1.3.2"]]}}

Top-level — for everyone on the project
Committed to git. Every developer gets these when they clone.

  (defproject my-app "0.1.0-SNAPSHOT"
    :plugins [[lein-ring "0.12.6"]
              [lein-ancient "0.7.0"]])

Inside a profile — conditional
Only active when that profile is active.

  :profiles
  {:dev
    {:plugins [[lein-test-refresh "0.25.0"]
               [lein-cljfmt "0.9.2"]]}

   :uberjar
    {:plugins [[lein-shell "0.5.0"]]}}

Most Useful Plugins

Web Development

  ;; Run Ring/Compojure apps with auto-reload
  [lein-ring "0.12.6"]
  lein ring server        ; open browser automatically
  lein ring server-headless
  lein ring uberjar       ; build deployable war

  ;; ring config in project.clj
  :ring
  {;; Required: your main handler function
   :handler my-app.core/app

   ;; Port (default 3000, overridden by $PORT env var)
   :port 3000

   ;; Auto-reload namespaces on file change
   :auto-reload? true

   ;; Which namespaces to watch for reload
   :reload-paths ["src"]

   ;; Run this function before server starts
   :init my-app.core/init

   ;; Run this function when server stops
   :destroy my-app.core/destroy

   ;; Open browser on start (default true with `lein ring server`)
   :open-browser? true

   ;; For WAR packaging: servlet name
   :war {:name "my-app"}}

Testing Ring Handlers

Use ring-mock — no server needed:

  :profiles {:dev {:dependencies [[ring/ring-mock "0.4.0"]]}}

  (ns my-app.core-test
    (:require [clojure.test :refer :all]
              [ring.mock.request :as mock]
              [my-app.core :refer [app]]))

  (deftest test-home
    (let [response (app (mock/request :get "/"))]
      (is (= 200 (:status response)))))

  (deftest test-not-found
    (let [response (app (mock/request :get "/missing"))]
      (is (= 404 (:status response)))))

  (deftest test-post
    (let [response (app (-> (mock/request :post "/users")
                            (mock/json-body {:name "Alice"})))]
      (is (= 201 (:status response)))))

Testing

  ;; Auto-run tests on file save
  [lein-test-refresh "0.25.0"]
  lein test-refresh

  ;; Test coverage report
  [lein-cloverage "1.2.4"]
  lein cloverage
  ;; generates target/coverage/index.html

Code Quality

  ;; Format code (like Prettier)
  [lein-cljfmt "0.9.2"]
  lein cljfmt check       ; show formatting issues
  lein cljfmt fix         ; auto-fix them

  ;; Linter — catches common bugs
  [jonase/eastwood "1.4.3"]
  lein eastwood

  ;; Suggest more idiomatic Clojure
  [lein-kibit "0.1.8"]
  lein kibit

Dependency Management

  ;; Check for outdated dependencies
  [lein-ancient "0.7.0"]
  lein ancient            ; check deps
  lein ancient :all       ; check deps + plugins
  lein ancient upgrade    ; auto-update versions

Finding Plugins

https://clojars.org — search for lein-*
https://github.com/technomancy/leiningen/wiki/Plugins — official plugin list

Aliases

Shortcuts that let you define custom lein commands in project.clj. Instead of typing long commands repeatedly, you define them once and run them with a short name.

Simple Aliases

Single task shortcut

  :aliases
  {"fmt"   ["cljfmt" "fix"]
   "lint"  ["eastwood"]
   "hints" ["kibit"]
   "dev"   ["ring" "server"]}

Example of call
lein fmt

Chaining Tasks with do

Run multiple tasks sequentially — use commas to separate task+args groups:

  :aliases
  {"ci" ["do"
         "clean,"
         "eastwood,"
         "kibit,"
         "test,"
         "uberjar"]}

lein ci ; clean → lint → analyze → test → build

Note: The commas are part of the syntax — they tell do where one task ends and the next begins.

Profile + Task Combos

  :aliases
  {"dev"      ["with-profile" "dev"     "ring" "server"]
   "prod-run" ["with-profile" "prod"    "run"]
   "ci-test"  ["with-profile" "test"    "test"]
   "build"    ["with-profile" "uberjar" "uberjar"]}

lein dev ; start dev server with :dev profile
lein build ; build production jar with :uberjar profil

Why AOT Compilation?

AOT = Ahead-Of-Time compilation

Normally Clojure compiles at runtime (when the JVM starts). AOT means
compiling to .class files before runtime, at build time.

The Problem It Solves
When you run a JAR, the JVM needs a standard Java entry point:
public static void main(String[] args)

Clojure's -main function is not that. It's a Clojure function that gets compiled on the fly when the JVM starts.

Without AOT, the JVM has no idea where to start. It can't find a main
method.

AOT compiles your -main namespace into real .class files with a proper Java main method the JVM can call directly.

What Happens With vs Without AOT ?

Without AOT (lein run):
JVM starts
→ loads Clojure runtime
→ Clojure compiles your namespaces on the fly
→ calls -main
(works fine because lein handles the startup)

With AOT (java -jar my-app.jar):
JVM starts
→ looks for main class in MANIFEST.MF
→ finds compiled .class file ← AOT produced this
→ calls -main
(works because the class file exists)

Concrete Example

(ns my-app.core
    (:gen-class))          ; ← this is also required! tells AOT to generate a
   class

  (defn -main [& args]
    (println "Hello!"))

Without :gen-class in the namespace declaration, even with :aot, the JVM won't find the entry point.

Why Only in the Uberjar Profile?

  :profiles
  {:uberjar {:aot :all}}   ; ← AOT everything for production jar

AOT has downsides in development:

Slower build — compiling everything takes time
Stale classes — if you change code, old .class files can cause confusing bugs
Bigger output — more files in target/

Clojure core.async: A Question & Answer Journey on Channels

ivan.gavlik — Fri, 13 Mar 2026 14:29:49 +0000

Introduction

core.async is Clojure's library for writing concurrent code without dealing with locks, callbacks, or complex threading.

Write asynchronous code that looks synchronous. Your code reads top-to-bottom, even though operations happen concurrently.

Components

Channels: queues that connect producers and consumers. They hold data temporarily and coordinate when to send and receive values
Operations: Non-blocking and blocking put and take operations for sending and receiving data
Go block: Place where you write sequential-looking async code

This post focuses exclusively on Channels. We'll explore Operations (>!, <!, >!!, <!!) and Go blocks in the next posts.

Channels

What exactly is a channel?

A channel is much more than a simple queue—it's a coordination mechanism that manages communication between independent processes

Internal Structure:

Every channel maintains four key components:

Buffer: Optional fixed-size queue holding values in transit. Can be:

nil (unbuffered - rendezvous semantics)
Fixed buffer (bounded queue)
Sliding buffer (drops oldest when full)
Dropping buffer (drops newest when full)

Take Queue: List of consumers waiting to receive values (when buffer is empty)

Put Queue: List of producers waiting to send values (when buffer is full)

Closed Flag + Lock: Thread-safe state management for the channel lifecycle

How data flow in the channel internal structure?

When you put a value on a channel, the implementation checks if any consumers are waiting. If so, the value is handed directly to a waiting consumer. If not, the value goes into the buffer (if there's space), or the producer joins the put queue to wait.

(require '[clojure.core.async :as a :refer [<! >! <!! >!! go go-loop chan close!]])

;; Unbuffered channel - producers and consumers must rendezvous
(def unbuffered-ch (chan))

;; Fixed buffer - can hold up to 10 values before blocking producers
(def buffered-ch (chan 10))

;; Sliding buffer - drops oldest values when full
(def sliding-ch (chan (a/sliding-buffer 5)))

;; Dropping buffer - drops newest values when full
(def dropping-ch (chan (a/dropping-buffer 5)))

;; Demonstration of buffer behavior
(let [ch (chan 2)]  ; Buffer size 2
  (go
    (>! ch 1)  ; Goes into buffer immediately
    (>! ch 2)  ; Goes into buffer immediately
    (println "Put two values")
    (>! ch 3)  ; Blocks here - buffer full, no consumer
    (println "Put third value"))

  (Thread/sleep 100)  ; Let producer run
  (go
    (println "First value:" (<! ch))   ; 1
    (println "Second value:" (<! ch))  ; 2
    (println "Third value:" (<! ch)))) ; 3 - now producer can complete

;; Output:
;; Put two values
;; First value: 1
;; Second value: 2
;; Put third value
;; Third value: 3

What is diff between buffered vs unbuffered channels?

Buffered channel = A mailbox where you can drop letters (items stored until someone picks them up).

Unbuffered channel = Handing something directly to someone (requires both people present at the same time).

Unbuffered channels have no storage capacity. They cannot hold any items at all.
When you do (chan) with no buffer size, you create a channel with a buffer size of 0. This means:

A producer trying to put a value must wait until a consumer is ready to take it
A consumer trying to take a value must wait until a producer is ready to give it
The value passes directly from producer to consumer in a "handshake" (No values are ever stored in the channel itself)

Important Note:
Both buffered and unbuffered channels work with all four operations: >!, <!, >!!, <!!
The difference is in when blocking/parking happens:

Buffered: Only blocks/parks when buffer is full (for puts) or empty (for takes)
Unbuffered: Always blocks/parks until handoff completes

What are use cases for buffered and unbuffered channels?

Buffered Channels Use case

I'm putting this in the queue for you to get to it when you can.

When producers generate data in bursts but consumers process steadily (e.g., user clicking buttons rapidly, but backend processes one request at a time).
When you want to queue up work without blocking the producer (e.g., logging system that accepts messages quickly while writing to disk happens in background)
Email Queue: Marketing system generates 10,000 emails instantly when campaign launches, but email server can only send 100 per minute. Buffer stores the emails while they're sent gradually.
Restaurant Order System: Kitchen receives orders in bursts during lunch rush (10 orders in 2 minutes, then nothing for 5 minutes). Buffer holds the orders so they're not lost, and kitchen processes them steadily.

Unbuffered Channels Use case

When you need confirmation that data was received before continuing (e.g., a worker acknowledging it accepted a task)

Worker Task Assignment: A manager hands work to a team member and waits until they confirm "I've got it" before walking away. You don't want to assume they took the task—you need to see them accept it.
Database Transaction Coordination: Service A completes a database write and must wait for Service B to acknowledge it read the data before A can proceed. Both must be synchronized at that exact moment.
Checkout Process: Customer submits payment, and the system must wait for payment gateway to confirm receipt before showing "Order Placed." Can't just fire-and-forget.
Handshake Protocols: Two systems establishing a connection—client sends "hello," waits for server to respond "hello back" before proceeding. Each step requires mutual acknowledgment.

What happens when a channel closes?

Closing a channel signals "no more values will ever be sent." This is the standard way to communicate completion in core.async pipelines.

Semantics:

Closed channels immediately return nil to all consumers
Attempts to put on a closed channel return false (or throw in blocking operations)
You can still drain values that were buffered before the close
Closing is idempotent—closing an already-closed channel is safe

(def ch (chan 5))

;; Producer sends values then closes
(go
  (>! ch 1)
  (>! ch 2)
  (>! ch 3)
  (close! ch)
  (println "Channel closed")

  ;; Attempting to put on closed channel
  (let [result (>! ch 4)]
    (println "Put after close returned:" result)))  ; false

;; Consumer loops until channel closes
(go-loop []
  (if-some [val (<! ch)]
    (do
      (println "Received:" val)
      (recur))
    (println "Channel closed, exiting")))

;; Output:
;; Received: 1
;; Received: 2
;; Received: 3
;; Channel closed
;; Put after close returned: false
;; Channel closed, exiting

Critical pattern: Use if-some or when-some to distinguish between:

nil because channel closed
nil as an actual value (though sending nil is discouraged)

;; Proper close detection
(go-loop []
  (when-some [val (<! ch)]  ; Continues only if val is non-nil
    (process val)
    (recur))
  ;; Loop exits when channel returns nil (closed)
  (println "Cleanup and shutdown"))

Key Takeaways

Channels are coordination mechanisms, not just queues. They manage the flow of data between independent processes.
Choose your buffer type wisely:
- Unbuffered: When you need rendezvous/handshake semantics
- Fixed buffer: For backpressure and controlled queuing
- Sliding buffer: When newest data matters most (like sensor readings)
- Dropping buffer: When you can afford to lose data under load
Always close channels when production is complete. This is how consumers know to stop waiting.
Use if-some/when-some to properly detect channel closure versus nil values.
Buffered channels decouple producers and consumers in time, while unbuffered channels force synchronization.

What's Next?

Now that you understand how channels work internally and when to use different buffer types, the next post will dive into Operations:

The difference between parking (>!, <!) and blocking (>!!, <!!) operations
When to use each operation type
How go blocks enable efficient concurrent programming
Composing channels with alts!, mult, pub/sub, and pipelines

Clojure Inheritance… Sort Of

Paula Gearon — Thu, 12 Mar 2026 05:49:43 +0000

Disclaimer

I want to start off by saying that I don't expect anyone to read this. However, neither OpenAI nor Anthropic's models get this right on the first try, so I figure that writing about it might get picked up in future training runs.

Inheritance

A pattern that I sometimes want in Clojure is to implement the same function for multiple types (defined by either defrecord or deftype). A simple way to do this is to do the work in an external function, and then have every implementation call it.

For instance, say I want to get a list of feet from several animal types. I can create a protocol for this, with the function get-feet:

(defprotocol Footed
  (get-feet [animal] "Get a sequence of feet"))

Then, I may have a few different groups of animals, each sharing a number of feet. I can create a function for each of these groups:

(defn get-2-feet [] [:left :right])

(defn get-4-feet [] [:front-left :front-right
                     :back-left :back-right])

(defn get-6-feet [] [:front-left :front-right
                     :middle-left :middle-right
                     :back-left :back-right])

Then the different record types will call the function they need:

(defrecord Ape [name]
  Footed
  (get-feet [_] (get-2-feet)))

(defrecord Bird [name]
  Footed
  (get-feet [_] (get-2-feet)))

(defrecord Cat [name]
  Footed
  (get-feet [_] (get-4-feet)))

(defrecord Ant [name]
  Footed
  (get-feet [_] (get-6-feet)))

…and so on.

This works, but it is very unsatisfying. It also gets noisy if the protocol has more than one function.

Instead, it would be nice if we could implement the protocol once, and then inherit this in any type that needs that implementation. Clojure doesn't support inheritance like this, but it has something close.

Protocols

A Protocol in Clojure is a set of functions that an object has agreed to support. The language and compiler have special dispatch support around protocols, making their functions fast and easy to call. While many people know the specifics of protocols, this often comes about through exploration rather than documentation. I won't go into an exhaustive discussion of protocols here, but I will mention a couple of important aspects.

Whenever a protocol is created in Clojure, two things are created: the protocol itself, and a plain-old Java Interface. (ClojureScript also has protocols, but they don't create interfaces). The protocol is just a normal data structure, which we can see at a repl:

user=>  (defprotocol Footed
  (get-feet [animal] "Get a sequence of feet"))
Footed
user=> Footed
{:on user.Footed,
 :on-interface user.Footed,
 :sigs {:get-feet {:tag nil, :name get-feet, :arglists ([animal]), :doc "Get a sequence of feet"}},
 :var #'user/Footed,
 :method-map {:get-feet :get-feet},
 :method-builders {#'user/get-feet #object[user$eval143$fn__144 0x67001148 "user$eval143$fn__144@67001148"]}}

This describes the protocol, and each of the associated functions. This is also the structure that gets modified by some of the various protocol extension macros. You may see how the :method-map refers to functions by their name, rewritten as a keywords.

Of interest here is the reference to the interface user.Footed. I'm using a repl with the default user namespace. Because we are already in this namespace, that Footed interface name is being shadowed by the protocol object. But it is still there, and we can still do things with it.

Common Operations

Protocols are often "extended" onto new datatypes. This is a very flexible operation, and allows new behavior to be associated with any datatype, including those not declared in Clojure (for instance, new behavior could be added to a java.util.String). This applies to Interfaces as well as Classes, which is something we can use here.

First of all, we want a new protocol/interface for each type of behavior that we want:

(defprotocol Feet2)
(defprotocol Feet4)
(defprotocol Feet6)

These protocols don't need functions, as they just serve to "mark" the objects that want to implement the desired behavior.

Next, we can extend the protocol with our functions onto the types described by each of these Interfaces:

(extend-protocol Footed
user.Feet2
(get-feet [_] [:left :right])
user.Feet4
(get-feet [_] [:front-left :front-right :back-left :back-right])
user.Feet6
(get-feet [_] [:front-left :front-right :middle-left :middle-right :back-left :back-right]))

Going back to the Footed protocol, we can see that it now knows about these implementations.

user=> Footed
{:on user.Footed,
 :on-interface user.Footed,
 :sigs {:get-feet {:tag nil, :name get-feet, :arglists ([animal]), :doc "Get a sequence of feet"}},
 :var #'user/Footed,
 :method-map {:get-feet :get-feet},
 :method-builders {#'user/get-feet #object[user$eval143$fn__144 0x67001148 "user$eval143$fn__144@67001148"]},
 :impls {
    user.Feet2 {:get-feet #object[user$eval195$fn__196 0x24fabd0f "user$eval195$fn__196@24fabd0f"]},
    user.Feet4 {:get-feet #object[user$eval199$fn__200 0x250b236d "user$eval199$fn__200@250b236d"]},
    user.Feet6 {:get-feet #object[user$eval203$fn__204 0x61f3fbb8 "user$eval203$fn__204@61f3fbb8"]}}}

Note how the :impls value now maps each of the extended interfaces to the attached functions.

A Comment on Identifiers

You might have noticed that I had to use the fully-qualified name for these interfaces due to the protocol name shadowing them. When a protocol is not in the same namespace, then it can be required, and referenced by its namespace, while the Interface can be imported from that namespace. For instance, a project that I've been working on recently has require/imports of:

(ns my.project
 (:require [quoll.rdf :as rdf])
 (:import [quoll.rdf IRI]))

In this example I am able to reference the protocol via rdf/IRI while the interface is just IRI.

Attaching

Now that the Footed protocol has been extended to each of these interfaces, the protocols associated with those interfaces can be attached to any type that wants that behavior.

Going back to our animals, we can do the same thing again, but this time without the stub functions that redirect to the common functionality:

(defrecord Ape [name] Feet2)
(defrecord Bird [name] Feet2)
(defrecord Cat [name] Feet4)
(defrecord Ant [name] Feet6)

Instances of these types will now pick up the implementations extended to these marker protocols:

(def magilla (Ape. "Magilla"))
(def big-bird (Bird. "Big"))
(def garfield (Cat. "Garfield"))
(def atom-ant (Ant. "Atom"))

user=> (get-feet magilla)
[:left :right]
user=> (get-feet big-bird)
[:left :right]
user=> (get-feet garfield)
[:front-left :front-right :back-left :back-right]
user=> (get-feet atom-ant)
[:front-left :front-right :middle-left :middle-right :back-left :back-right]

Final Declarations

After explaining so much of the mechanism, the code has been scattered widely across this post. Putting the declarations together, we have:

(defprotocol Footed (get-feet [_]))
(defprotocol Feet2)
(defprotocol Feet4)
(defprotocol Feet6)

(extend-protocol Footed
 user.Feet2
 (get-feet [_] [:left :right])
 user.Feet4
 (get-feet [_] [:front-left :front-right :back-left :back-right])
 user.Feet6
 (get-feet [_] [:front-left :front-right :middle-left :middle-right  :back-left :back-right]))

(defrecord Ape [name] Feet2)
(defrecord Bird [name] Feet2)
(defrecord Cat [name] Feet4)
(defrecord Ant [name] Feet6)

Wrap Up

Functional programming in Clojure is not generally served by having multiple types like this, but it does happen. While this is a trivial example, with only a single function on the protocol, the need for this pattern becomes apparent when protocols come with multiple functions.

I've called it inheritance, but that is only an analogy. It's not actually inheritance that we are applying here, but it does behave in a similar way.

Just What IS Clojure, Anyway?

Dimension AI Technologies — Sun, 08 Mar 2026 17:44:46 +0000

Look at this line of code:

processCustomerOrder(customer, orderItems)

Any developer with six months of experience knows roughly what that does. The name is explicit, the structure is familiar, the intent is readable. Now look at this:

(reduce + (map f xs))

The reaction most developers have is immediate and unfavourable. Parentheses everywhere. No obvious structure. It looks less like a programming language and more like a typographer's accident. The old joke writes itself: LISP stands for Lost In Stupid Parentheses.

That joke is, technically, a backronym. John McCarthy named it LISP as a contraction of LISt Processing when he created it in 1958. The sardonic expansion came later, coined by programmers who had opinions about the aesthetic choices involved. Those opinions have not mellowed with time.

And yet Clojure – a modern descendant of Lisp – ranked as one of the highest-paying languages in the Stack Overflow Developer Survey for several consecutive years around 2019. Developers walked away from stable Java and C# positions to build production systems in it. A Brazilian fintech used it to serve tens of millions of customers. Something requires explaining.

The ancestry: Lisp reborn

Clojure only makes sense against the background of Lisp, and Lisp only makes sense as what it actually was: not merely a programming language, but a direct implementation of mathematical ideas about computation.

McCarthy's 1958 creation introduced concepts that took the rest of the industry decades to absorb. Garbage collection, conditional expressions, functional programming, symbolic computation – all present in Lisp before most working developers today were born. Many programmers encounter Lisp's descendants daily without being aware of it.

The defining feature is the S-expression:

(+ 1 2)

Everything is written as a list. This is not merely a syntactic preference. Because code and data share the same underlying structure, a Lisp program can manipulate other programs directly. This property – homoiconicity – is the technical foundation of Lisp macros: code that generates and transforms other code at compile time, with a flexibility that few conventional infix languages match. It is the reason serious Lisp practitioners regard the syntax not as a historical curiosity but as a genuine technical advantage.

Lisp also, however, developed a reputation for producing work that individual experts could write brilliantly and teams could not maintain at all. The tension between expressive power and collective readability never fully resolved. Clojure inherits this tradition knowingly, and is aware of the cost.

What Clojure actually is

The brilliant Rich Hickey created Clojure in 2007. His central design decision was not to build a new runtime from scratch but to attach Lisp to an existing ecosystem.

Layer	Technology
Runtime	JVM
Libraries	Java ecosystem
Language model	Lisp

This host strategy gave Clojure immediate access to decades of mature Java libraries without needing to rebuild any of them. A Clojure developer can call Java code directly. The same logic drove two later variants: ClojureScript, which compiles to JavaScript and found real traction in teams already working with React, and ClojureCLR, which runs on .NET. Rather than fight the unwinnable battle of building its own ecosystem from scratch, Clojure attached itself to three of the largest ones that already existed.

Clojure does not attempt to displace existing ecosystems. It operates inside them.

Central to how Clojure development actually works is the REPL – Read–Eval–Print Loop. Rather than the standard write–compile–run–crash cycle, developers send code fragments to a running system and modify it live. Functions are redefined while the application continues executing. For experienced practitioners this is a material productivity difference: the feedback loop is short, and the distance between an idea and a tested result is small. Experienced Clojure developers report unusually low defect rates, a claim that is plausible given the constraints immutability places on the ways a programme can fail.

The Hickey doctrine: simple versus easy

Hickey's 2011 Strange Loop talk Simple Made Easy is the philosophical engine behind every design choice in Clojure. It draws a distinction that most language design ignores.

Term	Meaning
Easy	Familiar; close to what you already know
Simple	Not intertwined; concerns kept separate

Most languages pursue easy. They aim to resemble natural language, minimise cognitive friction at the point of learning, and reduce the effort required to write the first working programme. This also means that languages favoured by human readers tend to be the hardest for which to write parsers and compilers.

Clojure instead pursues simple. Its goal is to minimise tangled interdependencies in the resulting system, even at the cost of an unfamiliar surface. Writing parsers for Lisps is comparatively straightforward, at the cost of human readability.

Hickey's specific target is what he calls place-oriented programming: the treatment of variables as named locations in memory whose values change over time – mutability, in more formal terms. His argument is that conflating a value with a location generates incidental complexity at scale, particularly in concurrent systems. When you cannot be certain what a variable contains at a given moment, reasoning about a programme becomes difficult in proportion to the programme's size.

The design of Clojure follows directly from this diagnosis. Immutable data, functional composition, minimal syntax, and data structures in place of object hierarchies are all consequences of the same underlying position. The language may not feel easy. The resulting systems are intended to be genuinely simpler to reason about.

The real innovation: data and immutability

Clojure's core model is data-oriented. Rather than building class hierarchies, programmes pass simple structures through functions:

(assoc {:name "Alice" :age 30} :city "London")

This creates a new map. The original is untouched. That is the default behaviour across all of Clojure's data structures – values do not change; new versions are produced instead.

This is made practical by persistent data structures, which use structural sharing. When a new version of a data structure is produced, it shares most of its internal memory with the previous version rather than copying it entirely. The comparison that makes this intuitive for most developers: Git does not delete your previous commits when you push a new one. It stores only the difference, referencing unchanged content from before. Clojure applies the same principle to in-memory data.

The consequence for concurrency results directly from this. Race conditions require mutable shared state. If data cannot be mutated, the precondition for the most common class of concurrency bug does not exist. This was Clojure's most compelling practical argument during the multicore boom of the 2010s, when writing correct concurrent code had become a routine industrial concern rather than a specialist one. Clojure let developers eliminate that entire class of problem.

The functional programming wave – and why easy beat rigorous

Between roughly 2012 and 2020, functional programming moved from academic discussion to genuine industry interest. The drivers were concrete: multicore processors created pressure to write concurrent code correctly; distributed data systems required reasoning about transformation pipelines rather than mutable state; and the sheer complexity of large-scale software made the promise of mathematical rigour appealing.

Clojure was among the most visible representatives of this movement, alongside Haskell, Scala, and F#. Conference talks filled. Engineering blogs ran long series on immutability and monads. For a period it seemed plausible that functional languages might displace the mainstream ones.

What actually happened was different. Mainstream languages absorbed the useful ideas and continued. And the majority of working programmers, it turned out, rarely needed to reason about threading and concurrency at all.

Java gained streams and lambdas in Java 8. JavaScript acquired map, filter, and reduce as first-class patterns, and React popularised unidirectional data flow. C# extended its functional capabilities across successive versions. Rust built immutability and ownership into its type system from the outset. The industry did not convert to functional programming – it extracted what it needed and kept the syntax it already knew.

A developer who can obtain most of functional programming's benefits inside a language they already know will rarely conclude that switching entirely is justified.

The deeper reason functional languages lost the mainstream argument is not technical. It is sociological. Python won because it is, in the most precise sense, the Visual Basic of the current era. That comparison is not an insult – Visual Basic dominated the 1990s because it made programming accessible to people who had no intention of becoming professional developers, and that accessibility produced an enormous, self-reinforcing community. Python did exactly the same thing for data scientists, academics, hobbyists, and beginners, and for precisely the same reason: it is easy to learn, forgiving of error, and immediately rewarding to write. Network effects took care of the rest. Libraries multiplied. Courses proliferated. Employers specified it. The ecosystem became self-sustaining.

Clojure is the antithesis of this process. It is a language for connoisseurs – genuinely, not dismissively. Its internal consistency is elegant, its theoretical foundations are sound, and developers who master it frequently describe it with something approaching aesthetic appreciation. Mathematical beauty, however, has never been a reliable route to mass adoption. Narrow appeal does not generate network effects. And Clojure, by design, operates as something of a lone wolf: it rides atop the JVM rather than integrating natively with the broader currents of modern computing – the web-first tooling, the AI infrastructure, the vast collaborative ecosystems built around Python and JavaScript. At a moment when the decisive advantages in software development come from connectivity, interoperability, and the accumulated weight of shared tooling, a language that demands a clean break from everything a developer already knows is swimming directly against the tide.

Compare this with Kotlin or TypeScript, both of which succeeded in part because they offered a graduated path. A developer new to Kotlin can write essentially Java-style code and improve incrementally. A developer new to TypeScript can begin with plain JavaScript and add types as confidence grows. Both languages have, in effect, a beginner mode. Clojure has no such thing. You either think in Lisp or you do not write Clojure at all.

Where Clojure succeeded

Despite remaining a specialist language, Clojure has real industrial presence.

The most prominent example is Nubank, a Brazilian fintech that reached a valuation of approximately $45 billion at its NYSE listing in December 2021. Nubank runs significant portions of its backend in Clojure, and in 2020 acquired Cognitect – the company that stewards the language. That acquisition was considerably more than a gesture; it was a statement of long-term commitment from an organisation operating at scale.

ClojureScript found parallel influence in the JavaScript ecosystem. The Reagent and re-frame frameworks attracted serious production use, demonstrating that the Clojure model could be applied to front-end development at scale and not merely to backend data pipelines.

The pattern that emerges from successful Clojure deployments is consistent: small, experienced teams working on data-intensive systems where correctness and concurrency matter more than onboarding speed. That is a narrow niche. It was also, not coincidentally, a well-paid one – for a time.

Verdict: the ideas won

Clojure despite its brilliance and initial buzz has not become a mainstream language. By any measure of adoption – survey rankings, job advertisements, GitHub repositories – it remains firmly in specialist territory. Even F#, a functional rival with the full weight of Microsoft's backing - and easier syntax - has not broken through.

But the arguments Clojure made in 2007 has largely been vindicated. Immutability is now a design principle in Rust, Swift, and Kotlin. Functional composition is standard across modern JavaScript and C#. Data-oriented design has become an explicit architectural pattern in game development and systems programming. The industry did not adopt Clojure, but it has been grateful for Hickey's ideas and has in fact hungrily absorbed them.

What did not transfer was the syntax – and behind the syntax lay an economic problem that no philosophical vindication could resolve.

Developers and Heads of Technology might love Clojure for its expressive power and productivity. But a CTO and their C-suite peers evaluating a language does not ask only whether it is technically sound. The questions are: how large is the available talent pool? How long does onboarding take? What happens when a key developer leaves? Does it leave us exposed to key person risk? Clojure's answers to all of these questions are uncomfortable.

There is a further cost that rarely appears in language comparisons. A developer with ten years of experience in Java, C#, or Python carries genuine accumulated capital: hard-won familiarity with idioms, libraries, failure modes, and tooling. Switching to a Lisp-derived language does not extend that knowledge – it resets it. Clojure keeps the JVM underneath but discards almost everything a developer has learned about how to structure solutions idiomatically. The ten-year veteran spends their first six months feeling like a junior again. Recursion replaces loops. Immutable pipelines replace stateful objects. The mental models that took years to build are, at best, partially transferable. They might even fail entirely to transition to functional thinking, after decades in imperative and OOP styles. That cost and those risks are real and largely invisible in adoption discussions, and they fall on precisely the experienced developers an organisation most wants to retain. Knowledge compounds most effectively when it is built upon incrementally. Clojure does not permit that. It demands a clean break, and most organisations and most developers are not willing to pay that price.

The high wages Clojure commanded were not, from a management perspective, a straightforward mark of quality. They were a warning of risk, of "god programmer" lock-in. They reflected something less flattering than productivity: the classic dynamic of the expert who becomes indispensable by writing systems that only they can maintain. At its worst this approaches a form of institutional capture – a codebase so entangled with one person's idiom that replacing them becomes prohibitively expensive, something uncomfortably close to ransomware in its commercial effect.

That position has been further undermined by the rise of agentic coding tools. The practical value of writing in a mainstream language has dramatically increased, because AI coding assistants are trained on the accumulated body of code that exists – and that body is overwhelmingly Python, JavaScript, Java, and C#. The effect is concrete: ask a capable model to produce a complex data transformation in Python and it draws on an enormous foundation of high-quality examples. Ask it to do the same in idiomatic Clojure and the results are less reliable, the suggestions thinner, the tooling shallower. It might have to go through several rounds of trial-and-error. A language's effective learnability in 2026 is no longer a matter only of human cognition; it is also a function of training density. Niche languages are niche in the training data too, and that gap compounds. The expert moat – already questionable on organisational grounds – is being drained from two directions at once.

Clojure's ideas spread widely and rapidly through the languages that absorbed them and left the parentheses behind. Its practitioners, once among the best-paid developers in the industry, now find that the scarcity premium they commanded rested partly on barriers that no longer hold.

So, just what is Clojure, anyway? It is a language that was correct about the most important questions in software design, arrived a decade before the industry was ready to hear the answers, and expressed those answers in a notation the industry was not willing to learn.

The language was right about the future of programming. It might not be part of that future now that it has arrived. But it rightly deserves a place in computing history.

This article is part of an ongoing series examining what programming languages actually are and why they matter.

Language	Argument
C	The irreplaceable foundation
Python	The approachable language
Rust	Safe systems programming
Clojure	Powerful ideas, niche language

Coming next: Zig, Odin, and Nim – three languages that think C's job could be done better, and have very different ideas about how.

Datastar Observations

Howard M. Lewis Ship — Sat, 07 Feb 2026 23:35:22 +0000

I've been very impressed, so far, with Datastar, a tiny JavaScript library for front-end work; I've been switching a personal side-project from using Svelte for it's UI to Datastar, and as amazing as Svelte is, Datastar has impressed me more.

Datastar's essential concept is for the client to shift virtually all logic and all markup rendering back to the server; event handlers can succinctly call server endpoints, which return markup, and the markup is morphed into the running DOM. This makes the server-side is the system of record. Datastar has a nice DSL, based on data-* attributes, allowing you to do nearly anything you need to do in the client, declaratively.

Alternately, the server can start an SSE (server sent event) stream and send down markup to morph into the DOM, or JavaScript to execute, over any period of time. For example, my project has a long running process and it was a snap to create a modal progress dialog and keep it updated as the server-side process looped through its inputs.

The mantra of Datastar is to trust the morph and the browser -- it's surprisingly fast to update even when sending a fair bit of content. It feels wasteful to update a whole page just to change a few small things (say, mark a button as disabled) but it works, and it's fast, and it frees you from a nearly all client-side reactive updates (and all the related edge cases and unforseen consequences).

The server side is not bound to any particular language or framework (they have API implementations for Clojure, Java, Python, Ruby, and many others) ... and you could probably write your own API in an afternoon.

I especially like side-stepping the issue of needing more representations of data; the data lives server-side, all that is ever sent to the client is markup. There's no over-the-wire representation, and no parallel client-side data model. All that's ever exposed as endpoints are intentional ones that do work and deliver markup ... in other words, always use-case based, never schema based.

There's a minimal amount of reactive logic in the client, but the essence of moving the logic to server feels like home; Tapestry (way back in 2005) had some similar ideas, but was far more limited (due to many factors, including JavaScript and browser maturity in that time).

I value simplicity, and Datastar looks to fit my needs without doing so much that is magical or hidden. I consider that a big win!

DEV Community: clojure

Embabel agents as Clojure data

What Embabel is

Why Clojure

A Rosetta stone: the same agent, in both languages

If you prefer the annotations

The same tags, with named conditions

The hook: an agent is 626 bytes

Getting a platform, without a Java shell

Agent #1: the smallest thing that is still an agent

Agent #2: the order pipeline, and how modeling actually goes

Budgets and planners, as data

Agent #3: lazy conditions, the @Condition equivalent

Agent #4: talking to the model, with malli on both borders

Clojure functions as tools

Extension points, as functions

Durable history, and a process that survives its JVM

What the measurements say

Honest limits

Running it yourself

Quoting Difficulties

Symbol Reuse

Autogensym

Addressing the issue

Recap

Query Mess

Clojure Query DSLs

Macros

Structures

Quoting

Mixed Symbols

Unquoting

Wrap Up

Clojure vars - notes

Dig Deeper

Dynamic vars

Metadata

Symbol vs Var

Symbol

Var

Dig Deeper

Immutability

Vars and namespaces

Referring to another namespace

Dereferencing

Evaluation pipeline simplify

Dig Deeper

Special Symbols

' — Quote

#' — Var Quote

Advent of Code 2015 days 3-8 in Clojure

Day 03

Day 04

Day 05

Day 06

Day 07

Day 08

Parser?

End

Confidence Is Not Ownership

The Scoring Shape

What I Was Wrong About

The Failure Mode Hidden In Good Matches

Why Tenant Scope Belongs Inside The Algorithm

The Result

bisql (Clojure Data Access Library) released v0.4.0: Support Malli Validation

Bisql

Malli Support

Example of a generated query

Example of a generated schema

A Small Expression Language for if

Links

Leiningen — Complete Tutorial & Best Practices

Real world Example

Profiles

Plugins

Most Useful Plugins

Finding Plugins

Aliases

Why AOT Compilation?

Agent #3: lazy conditions, the `@Condition` equivalent

A Small Expression Language for `if`