DEV Community: clojure

Learning Clojure from Scratch - Make It Yours

Thiago Carvalho — Mon, 26 Oct 2026 03:01:46 +0000

This is part three of a series teaching Clojure to people with little or no programming experience.
In Part 1 you ran a web server on your computer.
In Part 2 you put it on the internet.

In this part you'll go from a website that says Hello, World! to a website with a home page, an about page, and a polite message for URLs that don't exist.

Step 1: Look at what the server receives

Before we start building the new pages, let's look at the information available to handler.

Temporarily change handler in src/app/core.clj so it sends the request back to you as text:

(defn handler [req]
  {:status  200
   :headers {"Content-Type" "text/plain"}
   :body    (pr-str req)})

Two changes: _req is now req because handler is using it, and the body is now (pr-str req), which means "print this value as text".

Remember the rhythm from Part 1: edit, stop, start, refresh.
Stop the server if it's still running (Ctrl+C), start it again with clojure -M:run, and open http://localhost:8080/hello?name=carvalho.
You'll see something like this (shortened here):

{:remote-addr "0:0:0:0:0:0:0:1",
 :headers {"accept" "text/html,...", "host" "localhost:8080", "user-agent" "Mozilla/5.0 ..."},
 :server-port 8080,
 :uri "/hello",
 :query-string "name=carvalho",
 :request-method :get,
 ...}

That's the request. It's a map, just like the response.
Two of its keys matter for this series:

:uri is the part of the address after the host name: /hello. We'll use it in this part to choose which page to show.
:query-string is whatever comes after the ?: name=carvalho. We'll use it in the next part.

Change the address to /about or /anything-you-like and watch :uri change.
Now that you know what a request contains, let's build the new pages.

Step 2: Send back HTML instead of plain text

Put handler back to saying hello (and req back to _req, since we're not looking at the request for now), but make it send HTML text.
Change Content-Type from text/plain to text/html and write HTML in the body:

(defn handler [_req]
  {:status  200
   :headers {"Content-Type" "text/html"}
   :body    "<h1>Hello, World!</h1>"})

Content-Type tells the browser how to read what it receives.
text/plain means "show it as text", text/html means "this is an HTML page, interpret the tags".
<h1>...</h1> is the HTML tag for a big heading.

Restart, refresh, and the greeting becomes a heading.

If you're new to HTML, a few tags will get you far:

<h1>Title</h1> for a heading.
<p>Some text</p> for a paragraph.
<a href="https://example.com">a link</a> for a link.
<ul> and <li> for a bulleted list: the <ul> is the list, and each <li> is one item in it.
<nav> for a group of navigation links. You'll see it in the next step.

Step 3: Create a reusable page template

Every page of a website needs the same frame: a title, some styling, a navigation bar, and so on.
Typing that for each page would get old quickly.
So let's write a function that takes the title and the content of a page and wraps them in a frame.

Add this above handler (Clojure reads a file from top to bottom, so a function has to be defined before the code that uses it):

(defn page [title body]
  (str "<!DOCTYPE html><html><head><title>" title "</title>"
       "<style>body{font-family:sans-serif;max-width:600px;margin:40px auto;padding:0 20px}"
       "nav a{margin-right:12px}</style></head><body>"
       "<nav><a href=\"/\">Home</a><a href=\"/about\">About</a></nav>"
       body
       "</body></html>"))

page receives two things, title and body, the same way handler receives req.
Most of the text inside it is the frame itself. The <style> and <nav> lines are decoration, so you don't need to understand them yet. Just type them in.

Two things to notice:

str joins things together into one piece of text. title and body get dropped between the other pieces.
To put a double quote inside a piece of text you write \", which is why href=\"/\" looks so busy. The backslash means "literally print this next character, I'm not trying to end the text."

Now use page to write two pages. Each one is a function with no inputs (that's the empty []), that returns HTML text:

(defn home-page []
  (page "Home"
        (str "<h1>Hi, I'm Carvalho</h1>"
             "<p>Welcome to my corner of the internet.</p>"
             "<ul>"
             "<li><a href=\"https://github.com\">GitHub</a></li>"
             "</ul>")))

(defn about-page []
  (page "About"
        (str "<h1>About Me</h1>"
             "<p>I'm learning Clojure and building my first website!</p>")))

str shows up again here, joining the lines of each body into one piece of text before page wraps it.

Put your real name and real links in home-page.
Nothing changes in the browser yet. In the next step we'll connect these pages to addresses so you can see them.

Step 4: Show the right page

You have two pages and one handler. The handler needs to look at :uri, which you saw in Step 1, and choose what page to show.

Replace handler with:

(defn handler [req]
  (case (:uri req)
    "/"      {:status  200
              :headers {"Content-Type" "text/html"}
              :body    (home-page)}
    "/about" {:status  200
              :headers {"Content-Type" "text/html"}
              :body    (about-page)}))

(:uri req) looks up the key :uri in the request map. (It's a Clojure shortcut: a keyword in the first position looks itself up in the map that follows.)
case then picks the option that matches that value: "/" gets the home page and "/about" gets the about page.

Restart and visit / and /about. You have a two-page website, with a navigation bar that works.

It works, but look at the two response maps: they're identical except for the :body.
Add a third page and you'd copy it a third time, and a fourth, and so on.
Whenever you catch yourself repeating the same work, consider moving it to a function so it can be reused.
Here's a small helper function that builds the response map.
The only thing that changes between pages, the body, becomes its input.
Add it above handler:

(defn html-response [status body]
  {:status  status
   :headers {"Content-Type" "text/html"}
   :body    body})

Now handler can shrink to this:

(defn handler [req]
  (case (:uri req)
    "/"      (html-response 200 (home-page))
    "/about" (html-response 200 (about-page))))

Restart and visit both pages again: nothing changed for the visitor, and your code is less repetitive.
The status is a parameter too, which is going to be handy in the next step.

Checkpoint: your website now has more than one page.

Step 5: Handle pages that don't exist

Visit http://localhost:8080/nothing-here.
Instead of something friendly, the browser shows No matching clause: /nothing-here.
case needs a match, and there wasn't one, so the server gave up (and answered with status 500, the web's code for "something broke on the server").

The fix is a catch-all as the last option: a page for "I don't know that one", with status 404, the web's code for "not found".
Add not-found-page above handler, and replace handler with the new version:

(defn not-found-page []
  (page "Not Found" "<h1>404 - Page Not Found</h1>"))

(defn handler [req]
  (case (:uri req)
    "/"      (html-response 200 (home-page))
    "/about" (html-response 200 (about-page))
    (html-response 404 (not-found-page))))

Look at the last line of case: it has only a result, with no match value in front of it.
case treats that as the default, the answer when nothing else matched.

Restart and try /nothing-here again.

The 404 page looks like any other page, so how do you know the status really is 404? Your browser keeps track.
Right-click the page, choose Inspect, open the Network tab and reload. The Status column shows 404 for /nothing-here, and 200 for / and /about.
Status codes are mostly for machines, like browsers and search engines, which need to know what happened without reading the page.

Checkpoint: your website now answers every address: with a page when it knows one, and with a friendly 404 when it doesn't.

The whole file

Here is the full src/app/core.clj at this point. If something isn't working, compare yours to this one:

(ns app.core
  (:require [org.httpkit.server :as http])
  (:gen-class))

(defn page [title body]
  (str "<!DOCTYPE html><html><head><title>" title "</title>"
       "<style>body{font-family:sans-serif;max-width:600px;margin:40px auto;padding:0 20px}"
       "nav a{margin-right:12px}</style></head><body>"
       "<nav><a href=\"/\">Home</a><a href=\"/about\">About</a></nav>"
       body
       "</body></html>"))

(defn home-page []
  (page "Home"
        (str "<h1>Hi, I'm Carvalho</h1>"
             "<p>Welcome to my corner of the internet.</p>"
             "<ul>"
             "<li><a href=\"https://github.com\">GitHub</a></li>"
             "</ul>")))

(defn about-page []
  (page "About"
        (str "<h1>About Me</h1>"
             "<p>I'm learning Clojure and building my first website!</p>")))

(defn not-found-page []
  (page "Not Found" "<h1>404 - Page Not Found</h1>"))

(defn html-response [status body]
  {:status  status
   :headers {"Content-Type" "text/html"}
   :body    body})

(defn handler [req]
  (case (:uri req)
    "/"      (html-response 200 (home-page))
    "/about" (html-response 200 (about-page))
    (html-response 404 (not-found-page))))

(defn -main [& _args]
  (let [port (Integer/parseInt (or (System/getenv "PORT") "8080"))]
    (println (str "Server running on port " port))
    (http/run-server handler {:port port})))

Deploy it

Same command as in Part 2:

vercel deploy --prod

Vercel remembers your project from last time, so it shouldn't ask you the setup questions again.
Open the link and click around. Visit /about, and then /nothing-here to see your 404 page live.
You didn't need to change Dockerfile.vercel from Part 2: it copies the whole src folder, so your new code goes along automatically.
Your website is getting more interesting!

If something went wrong

The browser shows old content: the running program still has the old code. Stop the server with Ctrl+C, start it again, and refresh.
Unable to resolve symbol: html-response (or home-page, page...): Clojure reads the file from top to bottom, so a function has to be defined above the code that uses it. Move it above handler, and check the spelling of the name.
Syntax error reading source or Unmatched delimiter: a parenthesis is missing or extra. Remember the "Break it on purpose" section in Part 1: the line number in the error is where to start looking.
The page shows <h1> and other tags as text: the Content-Type is still text/plain. It has to be text/html.
No matching clause: /something: case didn't find a match and has no default. Add the last line from Step 5.

What you learned

The request is a map too: :uri tells handler which page the visitor asked for, and :query-string holds what comes after the ?.
Content-Type tells the browser how to read the response. text/html makes it interpret the HTML tags.
str joins pieces of text, and page uses it to wrap any content in the same frame (title, styling, and navigation), so every page of your website looks similar.
home-page, about-page and not-found-page are functions that return HTML text, and handler uses case to pick one based on :uri.
When you catch yourself repeating the same work, move it into a function. html-response did that for the response map.
A function has to be defined above the code that uses it.
Status codes are part of the response: 200 means OK and 404 means not found. Without a default, case fails and the server answers with a 500.

In the next part we'll make a page that responds to what a user types, and you'll finally put :query-string from Step 1 to work.

Learning Clojure from Scratch - Put It on the Internet

Thiago Carvalho — Mon, 26 Oct 2026 03:00:11 +0000

This is part two of a series teaching Clojure to people with little or no programming experience.
In Part 1 you built a small website and ran it on your computer.

Right now the only person who can see your website is you.
In this part we'll fix that.
By the end you'll have a link you can open on your phone and send to a friend.

The server code barely changes. Most of the work is teaching the outside world how to run it.

What you need

On top of what you have from Part 1:

A free Vercel account. Vercel is where your website will run.
Node.js installed on your computer. We need it to install and run Vercel's command line tool.

To check that Node is installed, run npm --version in the terminal.

Open your my-site folder in VS Code and open a terminal (Terminal > New Terminal), just like last time.

Why a few things have to change

On your computer, you run a command and the program runs.
When someone else's computer runs it, three things need to be true:

The program has to listen on whichever port they tell it to, not the one you hard-coded.
The program has to be bundled into a single file, so it can be copied around.
They need a recipe that says how to build and start it.

We'll take these one at a time, and after each one you can check that your website still works.

Step 1: Let the outside world choose the port

In Part 1, you hard-coded the port as 8080 ((http/run-server handler {:port 8080})). Vercel requires that your program use a port they define in an environment variable.

Environment variables live outside your code, and you can look them up by name.
The one you'll use is called PORT.

Replace -main in src/app/core.clj with:

(defn -main [& _args]
  (let [port (Integer/parseInt (or (System/getenv "PORT") "8080"))]
    (println (str "Server running on port " port))
    (http/run-server handler {:port port})))

Read it from the inside out:

(System/getenv "PORT") asks "is there an environment variable called PORT?" You get its value, or nil (nothing) if there isn't one.
(or ... "8080") means "use PORT, or (if PORT is nil) use "8080" instead".
(Integer/parseInt ...) turns the text "8080" into the number 8080. Environment variables are always text, so we have to convert.
let gives a name to a value, so port refers to either the value of PORT or 8080.

Run it (clojure -M:run) and open localhost:8080. Nothing changed, because PORT was never defined.

Now stop the server (Ctrl+C) and start it with a port of your choosing:

PORT=3000 clojure -M:run

(On Windows PowerShell this would be $env:PORT=3000; clojure -M:run.)

The terminal now says Server running on port 3000.
Your website is now running at localhost:3000. It adapts to its environment.

Stop the server again with Ctrl+C.

Step 2: Bundle it into one file

Right now your program is a folder of source files plus a set of libraries that clojure downloads on demand.
To copy it to another machine, we want a single file with everything inside.
In the Java world that file is called a jar, and one that contains everything is called an uberjar.

We need three changes to create an uberjar.

First, add (:gen-class) to the ns at the top of src/app/core.clj:

(ns app.core
  (:require [org.httpkit.server :as http])
  (:gen-class))

This tells Java that this file can be the starting point of a packaged program.

Second, replace deps.edn with this. The only new part is the :build alias:

{:paths ["src"]
 :deps {org.clojure/clojure {:mvn/version "1.12.0"}
        http-kit/http-kit {:mvn/version "2.8.0"}}
 :aliases
 {:run {:main-opts ["-m" "app.core"]}
  :build {:deps {io.github.clojure/tools.build {:mvn/version "0.10.5"}}
          :ns-default build}}}

:run is still a shortcut for starting the program. :build is a shortcut for a tool, tools.build, that knows how to bundle a program.

Third, create a file called build.clj in the root of the project (next to deps.edn, not inside src):

(ns build
  (:require [clojure.tools.build.api :as b]))

(def class-dir "target/classes")
(def uber-file "target/app.jar")
(def basis (delay (b/create-basis {:project "deps.edn"})))

(defn uber [_]
  (b/delete {:path "target"})
  (b/copy-dir {:src-dirs ["src"] :target-dir class-dir})
  (b/compile-clj {:basis @basis
                  :src-dirs ["src"]
                  :class-dir class-dir})
  (b/uber {:class-dir class-dir
           :uber-file uber-file
           :basis @basis
           :main 'app.core}))

This is a program whose job is to build your program.
Read the steps in uber in order and you'll get the idea: delete the old target folder, copy the source in, compile it, and pack it together with all the libraries into target/app.jar.

Now build it:

clojure -T:build uber

The first time, Clojure downloads the build tool, so it can take a minute. It prints nothing when it succeeds. Check that target/app.jar appeared in the file explorer.

Then run the jar directly:

java -jar target/app.jar

Open localhost:8080. You should see Hello, World!.

Checkpoint: this is exactly what Vercel will do with your project. If it works here, the hard part is done.

Stop the server with Ctrl+C.

Step 3: Write the recipe

Create a file called Dockerfile.vercel in the root of the project:

FROM clojure:temurin-21-tools-deps AS build
WORKDIR /app
COPY deps.edn build.clj .
COPY src src
RUN clojure -T:build uber

FROM eclipse-temurin:21-jre-alpine
COPY --from=build /app/target/app.jar /app.jar
CMD ["/opt/java/openjdk/bin/java", "-jar", "/app.jar"]

This is the recipe Vercel follows to build and run your program.
Vercel looks for a file with exactly this name, and runs the result.

You don't need to understand the details of this file right now. Its shape is what matters. It has two parts, each starting with FROM:

Build. Start from a machine that has Clojure installed, copy in deps.edn, build.clj and src, and run: clojure -T:build uber.
Run. Start from a much smaller machine that has only Java, copy in app.jar, and start it using java -jar app.jar.

Step 4: Leave some things out

Create two more files in the root of the project.

.dockerignore lists things that shouldn't be sent to the build machine:

.git
.gitignore
target
.cpcache
README.md

.gitignore lists things you don't want to save into version control (when you start using Git, it will skip these):

.cpcache/
.clj-kondo/
.lsp/
target/
.vercel/

Step 5: Write some documentation

Add one more file called README.md so future-you remembers what this folder is:

# My Clojure website

Built following the "Learning Clojure from Scratch" series.

Your project should now look like this:

my-site/
  .dockerignore
  .gitignore
  Dockerfile.vercel
  README.md
  build.clj
  deps.edn
  src/
    app/
      core.clj

If you compare it with vercel-clojure, the template this series is based on, you'll find the same files. But you wrote them yourself, and you know why each one is there.

Step 6: Deploy

Install Vercel's command line tool:

npm i -g vercel

vercel login

In your browser, Vercel asks you to authorize your device. Once you do (you'll see a message like "Congratulations! You are now signed in."), run the command below to deploy:

vercel deploy --prod

The first time, Vercel asks a few questions about your project. When asked "Which project?", select "Create a new project". For the other questions, the suggested answers are usually fine. After you answer all of the questions, Vercel will build and deploy your website.

When it finishes you'll get a link that ends in vercel.app.
Open it. You should see Hello, World!.

That's your program, running in the cloud, reachable from anywhere in the world.

Checkpoint: open the link on your phone or another computer.

If something went wrong

vercel: command not found: the install in Step 6 didn't finish, or your terminal needs to be reopened.
The build fails on Vercel: the output in the terminal shows the failing line. The most common cause is a typo in build.clj or Dockerfile.vercel. If clojure -T:build uber works on your computer, the build step should work on Vercel.
The link shows an error page: first check that java -jar target/app.jar works locally. If it does, run vercel logs with your deployment's link to see what your program printed.
The link asks you to log in to Vercel: Vercel can protect some of the links it creates so only you can see them. Open the link labelled Production in the output of vercel deploy --prod, or find your project in the Vercel dashboard and use its production domain.

What you learned

Your program now reads its port from an environment variable (PORT) and falls back to 8080 when there isn't one, so the same code works on your computer and on Vercel.
An uberjar is a single file with your code and all of its libraries. clojure -T:build uber creates it and java -jar target/app.jar runs it.
build.clj is a small program whose job is to build your program, and the :build alias in deps.edn is how you call it.
Dockerfile.vercel is the recipe Vercel follows: one stage builds the jar, the other runs it.
Deploying means giving another computer a recipe and the files it needs. vercel deploy --prod does that, and the result is a link anyone on the internet can open.

We'll stop saying "Hello, World!" and put your own words and pages on the website.

Learning Clojure from Scratch - Hello, World

Thiago Carvalho — Mon, 26 Oct 2026 02:56:32 +0000

This is part one of a series of blog posts that ~~tries to~~ teaches you Clojure from scratch.
It assumes that you have little or no experience with programming.

By the end of the series you'll have your own Clojure website deployed to production:
a homepage, an interactive page, and a blog.

Some of it will be hard, and you won't understand everything we do to get there. Try to trust the process.
My primary goal is to help you experience success early (in the form of having your own website)
in the hope that it motivates you to continue your learning journey.
If you are curious and persistent, you should be able to complete this. Good luck!

In this first part we'll build a very small program and run it.

What you need

Clojure installed on your computer
Visual Studio Code installed on your computer

To check that Clojure is installed, open a terminal and run:

clojure --version

If it prints a version number, you're ready.

Clojure runs on the JVM (Java Virtual Machine), and the installation guide walks you through getting that too, so there is nothing extra to download if the command above works.
This series is written with macOS and Linux terminals in mind, but Windows should work too.

Create a project folder

Create an empty folder on your computer and call it my-site.
Open Visual Studio Code, click File > Open Folder, and choose my-site.

You'll see an empty file explorer on the left.
Everything you make in this series will live here.

Now click Terminal > New Terminal.
A panel opens at the bottom of the window.
A terminal is a place where you give your computer instructions by typing them.
This one starts "inside" your my-site folder, which is exactly where you want it.

Optional: open the Extensions panel (the squares icon on the left), search for Calva, and install it. It will make it easier to work with Clojure files and will allow you to do REPL-driven development in the future.

Step 1: Tell Clojure about your project

Create a new file called deps.edn in the root of your project
(hover over the file explorer and click the "New File" icon).
Paste or type this in:

{:paths ["src"]
 :deps {org.clojure/clojure {:mvn/version "1.12.0"}
        http-kit/http-kit {:mvn/version "2.8.0"}}
 :aliases
 {:run {:main-opts ["-m" "app.core"]}}}

You don't have to understand all of this yet, but here is a quick tour:

:paths ["src"] says "my code lives in a folder called src".
:deps lists the libraries this project uses. Clojure itself is one of them. The other is http-kit, a library that speaks HTTP, the language of web browsers.
:aliases defines shortcuts. :run is a shortcut that means "start the program whose entry point is called app.core".

The whole file is a map: a collection of keys (the keywords starting with :) and the values that go with them.

Make sure to save the file before moving to the next step.

Step 2: Write the program

Create a new file at src/app/core.clj.
That's a folder called src (src is short for source), with a folder called app inside it, with a file called core.clj inside that.
(If you type src/app/core.clj as the file name, VS Code will create the folders for you.)

The name app.core in deps.edn matches this path: src/app/core.clj.
Clojure uses the folders and file name to find your code.

One thing to know before we start: Clojure uses lots of parentheses.
Almost everything is written as (something and-then-its-arguments):
the first word says what to do, and the rest is what to do it with.
For example, (println "Hello") means "print the text Hello".
Every ( needs a matching ), and the same goes for [ with ] and { with }.
VS Code highlights matching pairs as you type, and if you lose one, Clojure will tell you. We'll try that on purpose near the end.

We'll write the file in three small pieces.

Piece 1: Define a namespace and require some code

(ns app.core
  (:require [org.httpkit.server :as http]))

ns is short for namespace.
The first line of your Clojure file defines the namespace you are working on (app.core) and the code it needs from other places in order to work.
Here we require org.httpkit.server from http-kit and give it the nickname http so we don't have to type the long name every time.

Piece 2: Handle requests

Add this at the bottom:

(defn handler [_req]
  {:status  200
   :headers {"Content-Type" "text/plain"}
   :body    "Hello, World!"})

A website is like a conversation: a browser sends a request and the server sends back a response.

   browser                        your program
  ---------                    ------------------
  GET /  ---- request ------>  handler
         <--- response ------  {:status 200 ...}

handler is the function that handles what to send back.
A function is a named piece of code that takes something in, does some work, and gives something back.
Here, handler takes in the request and gives back the response.

defn defines a function. Here you named it handler.
[_req] is the thing the function receives: the request from the browser. The leading underscore is a convention that means "I'm not using this yet".
The {...} is a map that defines the response: :status is a code (200 means "OK"), :headers describes the format of the response, and :body is what shows up on the screen.

Notice that in Clojure, calling a function returns whatever its last expression evaluates to. handler returns the map with :status, :headers and :body.

Piece 3: Create a main function and start the server

Add this at the bottom:

(defn -main [& _args]
  (println "Server running on port 8080")
  (http/run-server handler {:port 8080}))

-main is the function that runs when you start your program.
It prints a message, then starts a server with your handler.

& _args is for words typed after the program's name on the terminal. We're not using any, so ignore it for now.

8080 is a port, which you can think of as a numbered door on your computer.
Browsers will knock on door 8080 to talk to your program.

Here is the complete file:

(ns app.core
  (:require [org.httpkit.server :as http]))

(defn handler [_req]
  {:status  200
   :headers {"Content-Type" "text/plain"}
   :body    "Hello, World!"})

(defn -main [& _args]
  (println "Server running on port 8080")
  (http/run-server handler {:port 8080}))

Save it. Your project should now look like this:

my-site/
  deps.edn
  src/
    app/
      core.clj

Run it

In the terminal at the bottom of VS Code, type this and hit enter:

clojure -M:run

The first time, Clojure downloads the libraries from deps.edn. It can take a minute.
When it's done you'll see the message:

Server running on port 8080

The terminal now looks stuck, with no prompt coming back. That's correct: your server is running and waiting for visitors.

Open http://localhost:8080 in your browser.
localhost is a name that basically means "this computer".
You should see:

Hello, World!

Checkpoint: you just wrote a program that serves a web page. It works only on your computer, but you created a real (and very simple) web page!

Change something

Go back to src/app/core.clj and change the body from "Hello, World!" to "Hello, Clojure!". Save the file and refresh your browser.

Nothing changed. That's expected: the running program loaded the old code and doesn't know that the file changed.
Go to the terminal, press Ctrl+C to stop the server, then run clojure -M:run again and refresh the browser.

This is the rhythm for the next few parts: edit, stop, start, refresh.
(Clojure has a smarter way of working called REPL-driven development. We'll start using it in a future post.)

Break it on purpose

Reading errors is a good portion of programming, and it's easier when you know what broke. To get some practice, delete the very last character of the :body line (the ) right after the }), save, stop the server, and start it again.

You'll get an error that starts with Syntax error reading source and says EOF while reading, starting at line 4.
It's Clojure telling you "I reached the end of the file (EOF) and something that opened on line 4 was never closed".
Line 4 is where handler begins, so that's the place to look.
Put the ) back, restart, and you're back in business.

When you see a wall of error text, don't panic. The useful part is usually in the first or second line.

If something went wrong

clojure: command not found: Clojure isn't installed yet, or the terminal was opened before the install finished. Close VS Code, reopen it, and try again.
Address already in use: another program, or an earlier run of this one, is using port 8080. You'll still see Server running on port 8080 just before the error, because the message prints before the server tries to claim the port. Find the terminal where it's still running and press Ctrl+C. Alternatively, change your code to use another port (say 8081).
An error mentioning Could not locate app/core: the file isn't at src/app/core.clj. Check the folder and file names.
The browser says it can't connect: the server isn't running. Look at the terminal for an error, or for the prompt coming back, which means the program exited.

What you learned

Your website works like a conversation: a browser sends a request, and your program sends back a response.
A function takes something in, does some work, and returns something. handler, for example, takes the request and gives back a map describing the response.
deps.edn says what the project needs and creates aliases (like clojure -M:run).
src/app/core.clj holds the code for your handler (what to say) and -main (the starting point).
An error message is Clojure telling you where it got lost. Start reading the first and second lines before you panic.

In a future blog post we'll make handler smarter and we'll make a few small changes so the same program can run on someone else's computer via the internet.

Bonus: now that you are technically a Clojure developer, why not join the Clojurians community on Slack?

Getting Started with Clojure

vinayak — Fri, 23 Oct 2026 22:58:18 +0000

Introduction

Clojure is a functional programming language and dialect of the Lisp programming language, which means it use prefix notation for all its expressions, which runs on the Java Virtual Machine (JVM).

From Clojure's website: https://clojure.org

Clojure is a dialect of Lisp, and shares with Lisp the code-as-data philosophy and a powerful macro system. Clojure is predominantly a functional programming language, and features a rich set of immutable, persistent data structures. When mutable state is needed, Clojure offers a software transactional memory system and reactive Agent system that ensure clean, correct, multithreaded designs.

Clojure is a compiled and JVM-hosted language. It's compiler translates Clojure forms into JVM bytecode, which is then executed by the JVM. It also provides REPL (Read-Eval-Print Loop) support, this allows us to interactively evaluate Clojure expressions.

How Clojure code executes

Clojure code is executed in the following steps:

Clojure source code
Clojure Reader (Reads source into Clojure forms)
Clojure Compiler (Compiles Clojure forms into JVM bytecode)
JVM Execution (Executes the compiled bytecode)

Environment Setup

For compiling Clojure code, there are two popular ways to do this:

Using Leiningen (Build and project management)
Using Clojure CLI (Official command-line tool)

Using Clojure CLI

In the case of Clojure CLI, the project is configured manually, unlike Leiningen.

Creating a new project using Clojure CLI

In the case of Clojure CLI, new projects are created manually by setting up the folder structure and deps.edn files.

Folder structure for a Clojure CLI project typically looks like this:

where the project is configured using Clojure CLI deps.edn

running the project using Clojure CLI

clojure -M -m hello-world.core

running the REPL using Clojure CLI

clojure -M

Using Leiningen

creating a new project using Leiningen

lein new app hello-world

Folder structure for a Leiningen project typically looks like this:

where the project is configured using Leiningen (project.clj)

Running the project using Leiningen

lein run

Running the REPL using Leiningen

lein repl

Language Basics

Data Types Clojure supports several fundamental data types.

Type	Example	Description
Integer	`42`	Whole number without a decimal point
Float/Double	`3.14`	Numeric value with a decimal point
String	`"Hello"`	Text enclosed in double quotes
Boolean	`true`, `false`	Logical values representing true or false
Nil	`nil`	Represents the absence of a value
Keyword	`:name`	Named identifier commonly used as a key in maps
Symbol	`user-name`	Name used to refer to a value, function, or other entity
Character	`\A`	Represents a single character

(type 42)
;; => java.lang.Long
(type 12.09)
;; => java.lang.Double
(type "Hello")
;; => java.lang.String
(type :name)
;; => clojure.lang.Keyword
(def name "Vinayak")
(type name)
;; => java.lang.String

Difference between Keyword vs String vs Symbol:

;; Keyword
;; Define a map 
(def user {:name "Vinayak" :age 28})
;; Use
(println (:name user))
;; => "Vinayak"
(println (:age user))
;; => 28
(type user)
;; => clojure.lang.PersistentArrayMap
(type :name)
;; => clojure.lang.Keyword

;; String
(def name "Vinayak")
(println name)
;; => "Vinayak"
(type name)
;; => java.lang.String

;; Symbol -> represent a name literally
(type 'name)
;; => clojure.lang.Symbol

Variables

In Clojure, variables are immutable by default. Which means once a value is assigned, it can not be changed.

(def name "vinayak")
;; Try to change name directly
(set! name "vinayak sharma")
;; Execution error (IllegalStateException) at user/eval1577 (REPL:1).
;; Can't change/establish root binding of: name with set

But we can Re-definition using def again:

(def name "vinayak")
(def name "vinayak sharma")
(println name)
;; => vinayak sharma

Defining array

(def numbers [1 2 3 4 5])
(println numbers)
;; => [1 2 3 4 5]
(type numbers)
;; => clojure.lang.PersistentVector

Defining the map

(def user {:name "Vinayak" :age 28})
(println user)
;; => {:name "Vinayak", :age 28}
(type user)
;; => clojure.lang.PersistentArrayMap

Operators

(+ 10 5) ;; => 15
(- 10 5) ;; => 5
(* 10 5) ;; => 50
(/ 10 5) ;; => 2

(= 10 10) ;; => true, this is different from assignment
(not= 10 5) ;; => true
(< 5 10) ;; => true
(>= 10 10) ;; => true

(and true true) ;; => true
(or false true) ;; => true
(not true) ;; => false

In Clojure, arithmetic operation support multiple arguments. For example:

(+ 1 2 3 4) ;; => 10
(* 2 3 4) ;; => 24
(- 10 1 2) ;; => 7
(/ 100 2 5) ;; => 10

Compound Data Types
- Vector: Ordered collection, efficient indexed access.
- List: Ordered collection, efficient sequential access.
- Map: Stores key-value pairs.
- Set: Stores unique values.
Functions

In Clojure, functions are defined using the defn macro. Here is an example:

;; Define a function
(defn add [a b] 
    (+ a b))

;; Call the function
(add 10 20)
;; => 30

Quick Reference

Syntax	Meaning
`fn`	Creates a function
`[name]`	Defines a function parameter
`(str ...)`	Combines values into a string
`#()`	Shorthand syntax for an anonymous function
`%`	Represents the first argument in `#()`
`%1`	Represents the first argument in `#()`
`%2`	Represents the second argument in `#()`
`%&`	Represents the rest of the arguments in `#()`

Fundamentals

Conditionals
Loops

When to use what?

Construct	Purpose
`doseq`	Perform side effects for each item in a collection.
`for`	Generate a sequence of results.
`map`	Transform every item in a collection.
`reduce`	Combine items into a single result.
`loop/recur`	Implement custom iterative logic using recursion without growing the call stack

Atoms in Clojure: values are immutable by default. Atoms allow storing a value that can change over time or creates a mutable reference.

(def age (atom 25))
(println @age)
;; => 25
(println age)
;; #object[clojure.lang.Atom 0x3a14182a {:status :ready, :val 25}]
(reset! age 30)
(println @age)
;; => 30

Increase the value using a swap!

(def age (atom 25))
(swap! age inc)
(println @age)
;; Output: 26

Sequences

Function	Purpose	Example
`first`	Get the first item	`(first '(10 20 30))` → `10`
`rest`	Get remaining items	`(rest '(10 20 30))` → `(20 30)`
`seq`	Get a sequence view	`(seq [1 2 3])` → `(1 2 3)`
`map`	Transform every item	`(map inc [1 2 3])` → `(2 3 4)`
`filter`	Select matching items	`(filter even? [1 2 3 4])` → `(2 4)`
`count`	Count items	`(count '(10 20 30))` → `3`

Map & Records
Map: Maps are flexible key-value structures.

(def user
    {:id 101
    :name "Vinayak"
    :role "Engineer"})

(:name user)
;; => "Vinayak"

(assoc user :age 28)
;; => {:id 101, :name "Vinayak",
;; :role "Engineer", :age 28}

Records: Records are fixed-schema key-value structures.

(defrecord Employee [id name department])

(def emp
    (->Employee 101 "Vinayak" "Engineering"))

(:name emp)
;; => "Vinayak"

(assoc emp :location "Bangalore")
;; Returns a new record-like value with the extra key

Destructuring: Destructuring extracts values from collections and binds them to local names.

;; Vector destructuring
(let [[a b c] [1 2 3]]
    (println a b c))
;; => 1 2 3

(let [[a b c] [10 20 30]]
    (+ a b c))
;; => 60

;; Map destructuring
(let [{:keys [id name]} {:id 101 :name "Vinayak"}]
    (println id name))
;; => 101 "Vinayak"

;; Destructuring function arguments
(defn greet [{:keys [name]}]
    (str "Hello, " name))

(greet {:name "Vinayak"})
;; => "Hello, Vinayak"

Exception Handling

Clojure uses try, catch, and finally for exception handling.

(try
    (/ 1 0)
    (catch ArithmeticException e
    (println "Caught exception:" (.getMessage e)))
    (finally
    (println "Finally block executed")))

Using throw

(defn withdraw [balance amount]
    (if (> amount balance)
    (throw (ex-info "Insufficient funds"
                    {:balance balance
                        :amount amount}))
    (- balance amount)))

More on Clojure

Namespaces

Namespaces organize code into logical modules and prevent naming conflicts.

(ns my-app.core)


(ns myapp.payments)

(defn process-payment [amount]
    (str "Processing payment: " amount))
(process-payment 100)
;; => "Processing payment: 100"

Requiring namespaces in Clojure is done using the require function within the ns macro.

(ns my-app.core
    (:require [myapp.payments :as payments]))

Macros

Macros allow to extend the language by transforming code before it executes. Functions operate on values at runtime, whereas macros operate on code at compile-time.

defmacro: Used to define a macro.

(defmacro macro_name [condition & body]
    `(if (not ~condition)
        (do ~@body)))

(macro_name false
    (println "This will be printed"))
;; => "This will be printed"

Understand the Syntax

Syntax	Meaning
`defmacro`	Defines a macro
Backtick

``| Syntax-quotes a code form | |~| Unquotes and inserts a form | |~@` | Splices a sequence of forms into another form |

Watchers: A watcher observes changes to a reference type and runs a callback when its state changes. Watchers can be attached to atoms, refs, and agents.


clojure
(def balance (atom 100))

(add-watch balance :audit
    (fn [key reference old-value new-value]
    (println "Balance changed:"
        old-value "->" new-value)))

(reset! balance 200)
;; Prints a message about 100 -> 200

Note: fn is used to create an anonymous function

Agents: An agent manages state through asynchronous actions.


clojure
(def counter (agent 0))
(send counter inc)
(await counter)

@counter
;; => 1

send schedules an action on an agent's thread pool. await waits for actions dispatched before the call to finish.

Atom vs Agent in Clojure

Feature	Atom	Agent
State update	Synchronous	Asynchronous
Update operation	`swap!`, `reset!`	`send`, `send-off`
Read state	`@atom`	`@agent`
Main use	Independent shared state	Asynchronous state updates

Note: Atoms are suitable for managing independent shared state, while agents are ideal for handling asynchronous state updates.

Reference Values

Clojure provides several reference types for managing state, especially when concurrency is involved.

Atoms


clojure
(def x (atom 10))
(swap! x inc)
@x
;; => 11

Agent


clojure
(def counter (agent 0))
(send counter inc)
(await counter)
@counter
;; => 1


clojure
(def r (ref 0))
(dosync
    (alter r inc))
@r
;; => 1


clojure
(def ^:dynamic *my-var* 42)
*my-var*
;; => 42

Learning to code a new language with an AI tutor

Mark Blandford — Wed, 21 Oct 2026 12:30:00 +0000

I've been writing code in many different flavours for over 20 years. Everything from VBA, to Java, to Haskell. I wanted to get back into using a functional language, and Clojure had instant appeal. I already owned a book but after reading the first chapter, I thought I'd try something different: can AI actually teach me, rather than just doing the work for me? No Vibe Coding, no 'just tell me the answer', just a tutor to help me learn, the way I want to learn.

This post covers how I set up Claude Code as my tutor, what worked, what didn't, and my recommendations if you want to try something similar.

The app 👨‍💻

I have a large collection of event tickets (concerts, sports events etc.) and I wanted to build a 3-tier web app as an inventory of them. The app would have a SQLite database, and use Clojure for the API & front-end.

I defined the instructions & design first 📐

Before a single line of Clojure was written, I defined three things:

A set of instructions for the AI, which I saved in a CLAUDE.md file.
1. I used ChatGPT to help ensure my instructions were clear, unambiguous and specified the basics for coding with Clojure.
I created the data model for the application I wanted to build, and wrote it down in a data_model.md file.
I also created an OpenAPI spec for the endpoints of the APIs I knew my application would need, which I saved in openapi.yaml.

As you can see, this wasn't about just getting AI to do it for me. I devised the exact plan for the application I wanted to build, and I wanted the AI to help me learn how to implement it in Clojure. I defined how the application was to be structured and designed, leaving Claude Code to simply help me implement it using Clojure, and to explain the concepts I needed to understand along the way.

The instructions

A CLAUDE.md file, which Claude Code reads at the start of every session. It sets out:

What it is I'm wanting to do
The tech stack
The project structure
Most importantly, how I wanted to work/learn

Below is a snippet of the instructions, which I wrote before a single line of Clojure was written.

## Core Principles

### Test-Driven Development (TDD)

- **Always write tests first** before implementation
- Red → Green → Refactor cycle for every feature
- No code lands without corresponding tests

### Learning Through Building

- Explain Clojure concepts when introducing them
- Developer must write code, not just have Claude write it all.
  Consider when 'try and verify' should be used for new concepts
  and to cement learning.
- Include all explanations, lessons etc. in `/docs/training.md`
  so I can refer back to them later

There were three rules everything else relied on:

We write the tests first (TDD).
I write the code.
Every lesson & question gets written down.

The data model

How I wanted the SQLite database to be structured, and how the tables related to each other.

### Events

- id [auto] (Primary Key)
- name [string(150)]
- date [date] (Optional)
- unknownDate [boolean] (if date is unknown, default False)
- notes [string(1000)] (Optional)
- venueId [integer] (Foreign Key to `venue.id`)

Plus how they relate:

erDiagram
    VENUES ||--|{ EVENTS : hosts
    EVENTS ||--|{ TICKETS : has
    CONDITIONS ||--o{ TICKETS : describes
    TICKETS ||--o{ TICKET_IMAGES : has

From that, I also wrote an OpenAPI spec for the endpoints. None of it is complicated, for an experienced developer, but it meant I used the AI solely for learning, and I was still in control of the development process & structure.

Filling in the gaps 🧩

The approach I valued most is what I've been calling 'fill in the gaps'.

Rather than handing me a finished method, Claude would explain the concept, then give me a skeleton with some parts left blank. My task was then to fill in the blanks. If I got stuck, I would ask Claude for help. Everything I asked was logged in the docs/training.md file so I could refer back to it later.

Why does this work so well? This is the difference between reading an example and completing an exercise yourself. To fill in the blanks, I had to read and understand the code around it. Copying blocks of finished code teaches you very little; filling the gap makes you think (hard at times). This wasn't just copy and paste (I tried to avoid CTRL+C, CTRL+V as much as possible, and instead would type what I saw).

💡Tip: You don't need a special tool or instructions for this. Just ask: "Don't write it for me. Give me a skeleton with blanks and explain what goes in each."

Sometimes AI just did it anyway 🙈

It didn't always go to plan. Early on, while creating some of the database layer, Claude wrote the SQL file, the code that loads it and the tests, all without my input. Its reasoning was that it was 'just boilerplate'.

My response:

you have just created code without me. You're meant to be teaching me.

Claude acknowledged the mistake and saved the correction to its memory so it would apply in future sessions. From then on Claude largely stuck to the plan.

The lesson for me was that AI defaults to doing the work for you, even when you've written down that you don't want it to. You have to keep on top of it and notice when AI isn't behaving as expected.

I did make exceptions, however: wiring up a logging library wasn't something I wanted to learn that day, so I let Claude do it. I was OK with this as I made that decision and I was still achieving my goal of learning Clojure.

What I learned 📚

The training log is gold

Every explanation went into docs/training.md, which is now over 800 lines of notes written about my code, questions & mistakes. For example (as taken from the training log, generated by Claude):

Testing server-rendered HTML with `hickory` instead of substrings

## 2026-07-30 — Testing server-rendered HTML with `hickory` instead of substrings

The first version of `get-venues-renders-page` asserted on raw markup with
`str/includes?` and a regex counting `<li` occurrences. That style of
assertion has a real blind spot: it can't tell *where* text landed. This
came up for real — an earlier bug had venue names rendered as HTML
*attributes* instead of visible text (`<li id="1" venue="Anfield">`, empty
tag body), and the substring-based test still passed, because `<li` still
appeared twice in the markup. The test was checking the shape of the soup,
not what a browser would actually show a user.

Being able to ask 'why' is really important

The most valuable exchanges weren't 'how do I do X?'. Early on, a test called venue/create-venue!, yet there was no defn for it anywhere. I didn't understand where it came from. It turns out HugSQL reads a comment in the SQL file (-- :name create-venue! :<! :1) and creates the function when this line loads:

(hugsql/def-db-fns "sql/venue.sql"
  {:adapter (next-adapter/hugsql-adapter-next-jdbc)})

I also asked whether the :venue parameter was safe from SQL injection. Claude opened HugSQL's source and showed me the one function that swaps :venue for a ? placeholder. Claude didn't just tell me the answer, it showed me.

TDD worked well

In my TDD post I said that I struggle to practise 'full' TDD in languages I don't know well. With an AI tutor on hand to explain the test framework, it was much easier. I stayed test-first throughout.

It was (fairly) quick, and I understand it

In two days I had two working API endpoints and a working UI, with validation (for a single page), centralised error handling and styling, all test-first. More importantly, I could understand and explain the code, because I wrote it.

What didn't work so well 🚧

It was confidently wrong (sometimes)

Claude added a dependency, metosin/reitit-muuntaja, that simply doesn't exist (the right one was reitit-middleware).
The logging config it wrote had a -- inside an XML comment, which isn't allowed, and crashed every test run before any Clojure loaded.
The assertion pattern initially suggested by Claude in some of the unit tests was poor: it was asserting against substrings of the raw HTML rather than what would be rendered. It was only through my own experience and knowledge that I could see it could be give false positives, and needed improvement.

Green tests, broken page

We had passing tests, yet the page didn't render. My validation errors returned the right HTML and status code, and every test passed. Yet nothing appeared on screen: htmx quietly discards error responses unless you tell it otherwise. My tests never ran a browser, so they couldn't see it. I only found it by manually testing. Claude didn't spot this (and we've not yet implemented proper browser testing).

Its memory went stale

Claude keeps notes between sessions, but they aren't always current. When I came back after a break and asked 'where did we get to?', its notes said nothing had been committed since the first day; yet there had been a dozen commits since then. It corrected itself by checking git, but only because I asked. Trust but verify: don't assume the AI's memory is correct.

Recommendations ✅

If you want to learn a new language with an AI tutor, I recommend:

Own the design. Write the instructions and the application design yourself, before any code. It keeps you in charge and enables the AI to be the tutor of what you want to learn.
Ask for gaps, not answers. Ask for skeletons with blanks, and write that into the instructions.
Make it write everything down. Log every explanation to a file.
Keep TDD. Writing the tests was a great introduction to the language and syntax, with fast feedback: you don't need to have a working app to know if your syntax is correct etc., simply run the test.
Stay on your toes and trust your experience. When the AI oversteps, is mistaken, or suggests something that doesn't pass the sniff test, tell it.
Decide what it may write. Boilerplate, config and dependency wiring probably isn't the goal of your learning, so let the AI handle it (but record that it did).

Conclusion

I was frankly astonished at how well Claude Code worked as a tutor, though it needed my experienced eye to keep it on track, and it will do the work for you if you let it. Set the rules first, design the thing yourself and have the AI be your guide. Can I say I now 'know' Clojure? Not really, but I'm definitely more knowledgeable. Let's see where I am when I've completed the build.

Next time you reach for an AI assistant to build something, because you don't know how to, try asking it not to write the code. You may be surprised how much more enjoyable & rewarding that is.

Macro Macros

Paula Gearon — Wed, 26 Aug 2026 20:35:41 +0000

This is a follow up to my recent posts on Domain Specific Languages (DSLs) for database queries in Clojure, and different quoting forms in Clojure to enable this.

I had originally thought that I would write this post in a "Tutorial" style. But then it occurred to me that I used to get the best responses from people when I just documented what I learned as I learned it. I think it's a more "open" and personable style of writing, which may be what people liked. This approach might have extra appeal in the current era of AI slop, since people ought to see that I've written it myself. Unless I usually sound like an AI 🙃

I'm also hoping that this approach will be easier to write, since I don't need to restructure my exploration as an instructional post.

On the other hand, it may be a terrible idea. But I won't know unless I try…

Graph Queries

SQL is very structured around column selection, so it does not usually need anything like variables inside a query. This allows HoneySQL to build most of its structures using functions that take keywords and values as arguments.

On the other hand, graph query languages like Datomic, SPARQL, and GQL typically use pattern matching on the graph, where parts of the pattern contain a variable that will be "bound" to associated values when a pattern matches. For instance:

?person :hasFriend ?friend

… is a pattern for matching edges in a graph where something is connected by a property labelled :hasFriend to another node. Every edge in the graph that matches this pattern, leads to a pair of nodes that the variables ?person and ?friend get bound to.

GQL would do something similar with a MATCH clause of:

(person:Person)-[:HAS_FRIEND]->(friend:Person)

Like the SPARQL form, this binds the first node (which must be of type Person) to the variable person, and the second node (which is also a Person) to the variable friend.

I'm focused on Datomic and SPARQL, which are more closely related to each other, so I won't address GQL here.

The issue with variables is that keywords are already being used in queries (such as for the :hasFriend property), so we need something else. The obvious candidate is the Symbol, and this is the route that Datomic took.

However, Clojure uses symbols to refer to values, meaning that they need to be inserted in queries without being evaluated. That was why I did that post on quoting symbols: quoting is a mechanism to create a symbol as a part of a structure without asking Clojure to instead insert the value the symbol references. i.e. if I say:

(let [?person "bad data"]
  [?person :hasName "Fred"])

;; returns=> ["bad data" :hasName "Fred"]

This isn't what I wanted. It is even worse if I don't have ?person predefined (as the let expression does), since the code can't even run.

Instead, I want the symbol in the first position:

(let [?person "bad data"]
  ['?person :hasName "Fred"])

;; returns=> [?person :hasName "Fred"]

This doesn't care if the symbol is defined or not. We get back the structure that we wanted with a symbol in it.

Flint

A colleague has been using Flint to build SPARQL queries programmatically. I like Flint, because it uses Datomic-style queries to express SPARQL. Datomic has been designed to use from Clojure, with a query language based in Clojure data structures. So Flint should make it just as easy to query SPARQL.

However, because the queries are being built programmatically, we run the risk of reusing a variable name each time a new expression is added into the query. Reusing a variable for a different purpose will generally break a query, so he was generating new variable names whenever he was generating a new query clause.

There are a couple of ways to generate new variables for a query. One way is to generate a new name, build a symbol with that name, and then insert it without quoting the name being used to carry that symbol:

(let [?container (gensym "?container")]
  [[:my-object :contains ?container]
   [?container :value "hello"]])

;; result=> [[:my-object :contains ?container180]
;;           [?container180 :value "hello"]]

Another approach is to use an auto gensym:

`[[:my-object :contains ?container#]
  [?container# :value "hello"]]

;; result=> [[:my-object :contains ?container__2__auto__]
;;           [?container__2__auto__ :value "hello"]]

Both of these seem fine, but it gets harder to read and write when new constraints are added. For instance, I may be looking for a :value that is a string containing the substring "lo":

(let [?container (gensym "?container")
      ?value (gensym "?value")]
  [[:my-object :contains ?container]
   [?container :value ?value]
   [:filter '(contains ~?value "lo")]])

;; result=> [[:my-object :contains ?container140]
;;           [?container140 :value ?value141]
;;           [:filter (contains (clojure.core/unquote ?value) "lo")]]

Which doesn't work. We need syntax quoting instead:

(let [?container (gensym "?container")
      ?value (gensym "?value")]
  [[:my-object :contains ?container]
   [?container :value ?value]
   [:filter `(contains ~?value "lo")]])

;; result=> [[:my-object :contains ?container144]
;;           [?container144 :value ?value145]
;;           [:filter (user/contains ?value145 "lo")]]

Again… the quoting didn't work:

(let [?container (gensym "?container")
      ?value (gensym "?value")]
  [[:my-object :contains ?container]
   [?container :value ?value]
   [:filter `(~'contains ~?value "lo")]])

;; result=> [[:my-object :contains ?container148]
;;           [?container148 :value ?value149]
;;           [:filter (contains ?value149 "lo")]]

To be fair, I did know how to quote that all along, but I wanted to demonstrate that it can catch people out.

Another Step

This is all very contrived. But what about if I want to construct something more complex. Say, I want a general way to select an entity and its contained value, and then I decide that I want to filter that by containing "lo". The first part would be in a function, but I will need to provide the binding ?value variable to filter on it:

(defn select-entity-value [?entity ?value]
  (let [?container (gensym "?container")]
    [[?entity :contains ?container]
     [?container :value ?value]]))

(let [?e (gensym "?e")
      ?v (gensym "?v")]
  `[~@(select-entity-value ?e ?v)
    [:filter (~'contains ~?v "lo")]])

;; result=> [[?e178 :contains ?container180]
;;           [?container180 :value ?v179]
;;           [:filter (contains ?v179 "lo")]]

Splice-unquoting like this (the ~@ syntax) isn't really necessary, though quoting everything means that the expression inside the :filter doesn't need its own quoting (since it is a list, and we have to quote lists, or else they get executed).

We could even avoid almost quotes with:

(let [?e (gensym "?e")
      ?v (gensym "?v")]
  (conj (select-entity-value ?e ?v)
        [:filter (list 'contains ?v "lo")]))

But now we have conj and list in the expression, we're still quoting contains, and we have the messy gensym declarations at the top. This DSL doesn't look all that easy to use.

Filters and Bindings

Until now, I've been rehashing what I've talked about already, and some of the things my colleague was building. It all worked, but it just looked… clunky. I found myself thinking that surely we could do better, right?

Patterns are not too complex to work with, since they are just short vectors, containing keywords, symbols, or simple values like strings and numbers. The mess really showed up when we tried to introduce a filter.

The filter we used here was the contains function. There are a lot of other functions in SPARQL, so there isn't anything particularly special about that function. Hopefully, whatever we do to address one function could be applied to all of them.

It would be nice to just insert the contains expression directly into the query. Something like:

[:filter (contains ?v "lo")]

Bindings work similarly, except instead of evaluating an expression and passing through everything that returns a true result, they evaluate an expression and save it in a variable. For instance, to save a the lower-case form of the string ?v, you can bind it:

[:bind (lcase ?v) ?lowv]

The problems here are that contains and + looks like a function. Even if we created a function for it, the ?v is not bound to anything, so the function would fail. However, Clojure macros can accept any symbol as an argument. Can we use them somehow?

Macros are Clojure code that generates Clojure data. The trick is that the macro is called during compilation, and the resulting data is inserted into the source code before it gets compiled. This lets you generate code using code.

Clojure itself uses macros everywhere. Most of the "built in" syntax is actually just macros that write out other code. At the end of the day, Clojure only contains a few "special forms" that get presented to the compiler. But don't let that list of special forms fool you: many of those (e.g. defn, fn, and let) are actually macros as well, with simpler special forms underlying them.

Many of these macros accept symbols that are not bound, safely generating code that uses those symbols. For instance, consider an expression for an identity function: (fn [x] x)

We can see what the fn macro expands to by using macroexpand:

=> (macroexpand '(fn [x] x))
(fn* ([x] x))

This is just a rewrite to use fn* instead, which is much simpler: fn* does not do argument destructuring, it does not handle pre nor post conditions, it does not attach metadata, and it always expects parentheses around a function argument list and body even when there is only a single arity.

But importantly, notice how we can provide fn with an expression that includes x and it returns a new expression that also includes x? We don't need x to exist before doing this. That may be what we need.

Let's try it out. Can we create a contains macro that accepts a symbol argument and returns a list with appropriate symbols in it?

My first attempt was laughable:

(defmacro contains [a b] `(~'contains ~a ~b))

So when I call (contains "foot" "foo") it should return a list containing the symbol contains, the string "foot" and the string "foo". That was what was returned, but then that goes to the compiler, and the symbol contains doesn't exist, so it fails. Doh.

I needed an actual symbol object in the position of contains:

(defmacro contains [a b]
 (let [c# (symbol "contains")]
  `(~c# ~a ~b)))

But I didn't need to evaluate that to know what it would do… calling (contains "foot" "foo") would generate the list (contains "foot" "foo") and that would be evaluated, which then repeats the process until the macro evaluation overflows the stack. I had forgotten that I'm not returning the data structure anymore. Now I'm returning code that evaluates to the required data structure.

Aside from quoting a list (which gets tricky, because macro expansion essentially unquotes what you've quoted, so you need to double-quote), you can create a list with the list function:

(defmacro contains [a b]
 (let [c# (symbol "contains")]
  `(list ~c# ~a ~b)))

How does this look?

=> (macroexpand '(contains "foot" "foo"))
(clojure.core/list contains "foot" "foo")

Oh. That was sort of obvious in hindsight.

Let's forget inserting the symbol and just put it in place:

(defmacro contains [a b]
 `(list (symbol "contains") ~a ~b))
=> (macroexpand '(contains "foot" "foo"))
(clojure.core/list (clojure.core/symbol "contains") "foot" "foo")
=> (contains "foot" "foo")
(contains "foot" "foo")

See why I don't usually like writing this way? Showing how long it takes to get to something that should be easy is embarrassing.

But I'm really not happy about embedding the symbol by generating one based on a string. Is there another way? What if I quote it?

(defmacro contains [a b] `(list 'contains ~a ~b))
=> (macroexpand '(contains "foot" "foo"))
(clojure.core/list (quote user/contains) "foot" "foo")

That got me part of the way there, but I forgot that I'm in a syntax quote, so contains is resolved with its full namespace. I can write out (quote ~'contains), but I'm curious… can I just chain the quote/unquote syntax here?

(defmacro contains [a b] `(list '~'contains ~a ~b))
=> (macroexpand '(contains "foot" "foo"))
(clojure.core/list (quote contains) "foot" "foo")
=> (contains "foot" "foo")
(contains "foot" "foo")

I might stick to the (quote …) form though, since cascading quote/unquote could get hard to read. It turns out that this mattered later on.

Arguments

That did work, but what about the arguments? Right now they are being passed through, and they just appear verbatim in the final form. That doesn't work for variables like ?value:

=> (contains ?value "foo")
Syntax error compiling at (REPL:1:1).
Unable to resolve symbol: ?value in this context

We need to quote the arguments too.

(defmacro contains [a b] `(list (quote ~'contains) (quote ~a) (quote ~b)))
=> (macroexpand '(contains ?v "foo"))
(clojure.core/list (quote contains) (quote ?v) (quote "foo"))
=> (contains ?v "foo")
(contains ?v "foo")

This looked great! Until my colleague pointed out that he couldn't pass non-literal values into the macro. Of course he couldn't 🤦‍♀️

In this case, I need to check if the argument is a symbol, and if it is, then look for the form ?name or $name (SPARQL allows either ? or $ to indicate a variable). I'll create a helper function that tests if an argument is a symbol that starts with one of these characters, and only quote the ones that match. However, a function like that can't just return (quote a), since that just evaluates to a and won't get inserted into the output correctly. Instead, I need to return a list of the form (quote a):

(defmacro contains [a b]
 (let [vquote (fn [s]
               (if (and (symbol? s) (#{\? \$} (first (name s))))
                 (list 'quote s)
                 s))
       a# (vquote a)
       b# (vquote b)]
   `(list (quote ~'contains) ~a# ~b#)))

user=> (macroexpand '(contains ?v "foo"))
(clojure.core/list (quote contains) (quote ?v) "foo")
user=> (macroexpand '(contains v "foo"))
(clojure.core/list (quote contains) v "foo")

OK, I'll admit it… it took me a few iterations to get that right. Quoting quote was not something I was expecting.

Macro Macros

This works for contains, but what about all the other SPARQL functions? Do I have to write this out for all of them as well? Then there are functions like regex that can take 2 or 3 arguments.

It would be nice if I could take a function name, and generate the appropriate macro.

Except, macros are just code, and macros generate code. So I could always try generating a macro with a macro, right?

Well, sort of. It turned out to be harder than I thought.

Let's try creating a macro that generates a macro for a single-argument function, like lcase. I decided to skip the argument handling to start with, just to get the basic structure down. So my first attempt was:

(defmacro sparql-fn1 [s]
 `(defmacro ~s [~'a] `(list (quote (unquote ~s)) ~'a)))

This made it clear that I wasn't really sure of how to perform the (quote ~'contains) when I didn't have a literal value to put into the quoted position.
I thought I'd try it anyway, and it complained about "No such var: user/s", which didn't really surprise me. So let's see, what did it look like? I'll reformat the output so it's not all on a single line:

=> (macroexpand '(sparql-fn1 lcase))
(do (clojure.core/defn lcase
      ([&form &env a]
       (clojure.core/seq
         (clojure.core/concat
           (clojure.core/list (quote clojure.core/list))
           (clojure.core/list
             (clojure.core/seq
               (clojure.core/concat
                  (clojure.core/list (quote quote))
                  (clojure.core/list
                    (clojure.core/seq
                      (clojure.core/concat
                        (clojure.core/list (quote clojure.core/unquote))
                        (clojure.core/list user/s)))))))
           (clojure.core/list (quote user/a))))))
    (. (var lcase) (setMacro))
    (var lcase))

Let's remove the clojure.core namespaces, the redundant seq calls, and use some quoting syntax:

(do (defn lcase
     ([&form &env a]
      (concat
        (list 'list)
        (list (concat
                (list 'quote)
                (list (concat
                        (list 'unquote)
                        (list user/s)))))
        (list 'user/a))))
    (. (var lcase) (setMacro))
    (var lcase))

This helped me figure out where I'm passing things in poorly, but there was something much more important going on here.

The returned data structure was not the code to call defmacro but instead was a do block with 3 steps:

Define a function called lcase. This takes 3 arguments, prepending &form and &env before the argument I had declared.
Defining a function creates a var for it. The second step calls setMacro on that var.
Returns the lcase var.

The arguments &form and &env are explained in the Clojure docs as special variables that are available inside macros without having to declare them. We are seeing this being set up.

Also, rather than creating a "macro", a function is being created that is then converted to a macro. I'd seen elements of this before, but I'd never really dug into it. This prompted me to look at the defmacro source (by typing (source defmacro) a the repl), and… yes, this is what it's doing.

Most surprisingly, the code of the macro is not in the function, but rather the list structure of the macro is being constructed and returned. Reading the body, it looks like the final structure evaluates to:

(list 'list (list 'quote (list 'unquote user/s)) 'user/a)

The user/s part came about due to my unfortunate quote/unquote structure, and the user/a is because of how I'm calling macroexpand, but the rest of it actually evaluates to what I was expecting, to wit:

(list (quote (unquote user/s)) user/a)

And that structure would evaluate to what gets inserted into source code.

So the function here generates a structure that evals to what the macro returns, which then evals a second time to what gets inserted into the source.

So I can manually create a macro by creating a function that needs to evaluate twice to create the final code structure. That's going to be confusing.

But then I realized that I don't have to worry about the quote/unquote mess anymore. If I want to quote something, then using quote does not hide the quoted value, because now I am creating a list where quote is the first element, and the thing to be quoted is exactly what I want. So it's more complex, but more flexible.

Let's try then. To start with, I decided on a form that just takes all of its arguments, and wraps each one in the helper function that quotes it if the argument is a symbol starting with $ or ?.

(defmacro sparql-fn
  [s]
  (let [argq# (fn [a]
                (list 'if (list 'and (list 'symbol? 'a) (list #{\? \$} (list 'first (list 'name 'a))))
                      (list 'list (list 'quote 'quote) a)
                      a))]
    (list 'do
          (list 'defn s
                '[&form &env & args]
                (list 'list
                      (list 'quote 'cons)
                      (list 'list (list 'quote 'quote) (list 'quote s))
                      (list 'concat
                            (list 'list (list 'quote 'list))
                            (list 'map
                                  (list 'fn '[a] (argq# 'a))
                                  'args))))
          (list '. (list 'var s) '(setMacro))
          (list 'var s))))

This took me a few attempts, but it worked out pretty well:

=> (sparql-fn contains)
#'user/contains
=> (sparql-fn lcase))
#'user/lcase
=> (contains ?x "lo")
(contains ?x "lo")
=> (lcase "Hello")
(lcase "Hello")
=> (lcase a)
Syntax error compiling at (REPL:1:1).
Unable to resolve symbol: a in this context

Let's see what the generated code looks like:

=> (macroexpand '(sparql-fn lcase))
(do
  (defn lcase
   [&form &env & args]
   (list (quote cons)
         (list (quote quote) (quote lcase))
         (concat
           (list (quote list))
           (map (fn [a]
                 (if (and (symbol? a) (#{\? \$} (first (name a))))
                   (list (quote quote) a)
                   a))
                args))))
  (. (var lcase) (setMacro))
  (var lcase))

How does the returned list structure eval then? Working it manually, I came up with:

(list 'cons (list 'quote 'lcase) (concat '(list) (map (fn [a] …) args))))

The function here was a bit long, so I elided it. It's looking good, but evaluating it one more time, gets us to:

(cons (quote lcase) (list (map (fn [a] …) args)))

Which, when called as (lcase "Hello") should return a list containing 'lcase followed by the function mapped over all arguments. The function returns its input for a string, so the final list would be (lcase "Hello").

Similarly, for (lcase ?value) it's the same kind of thing, but now the function will return a list of (quote ?value), so the final output will be (lcase (quote ?value)).

There is no checking on the arguments at all, but I know that Fink is already doing that kind of work, so I thought this was where I could stop.

Small Issue

At this point I decided to try it with all of the SPARQL functions, and immediately hit a wall with concat. This is a function that appears in both SPARQL and in the above macro. As soon as concat is declared as a SPARQL macro, then the next thing I try to declare as a SPARQL macro will use the new concat macro instead of clojure.core/concat. Fink also tries to map and to SPARQL's &&, so that should be addressed as well:

(defmacro sparql-fn
  [s]
  (let [argq# (fn [a]
                (list 'if (list 'clojure.core/and (list 'symbol? 'a) (list #{\? \$} (list 'first (list 'name 'a))))
                      (list 'list (list 'quote 'quote) a)
                      a))]
    (list 'do
          (list 'defn s
                '[&form &env & args]
                (list 'list
                      (list 'quote 'cons)
                      (list 'list (list 'quote 'quote) (list 'quote s))
                      (list 'clojure.core/concat
                            (list 'list (list 'quote 'list))
                            (list 'map
                                  (list 'fn '[a] (argq# 'a))
                                  'args))))
          (list '. (list 'var s) '(setMacro))
          (list 'var s))))

Finally, I can write SPARQL queries using Fink with clean filters:

['[?entity :contains ?c]
 '[?c :name ?name]
 [:filter (contains ?name "lo")]]

Wrap Up

Well, this wasn't a tutorial. It was more like a litany of my mistakes as I stumbled towards understanding. I'm sure an LLM could have told me how to do this immediately, but then I wouldn't have learned anything.

I have no idea if anyone else will ever read this, but if you did, then thanks. If not, then that's OK. Writing these things down helps my clarify and consolidate what I learned. This is something I used to do regularly a long time ago, and I should do more of it.

As per my AI policy, I'm going to leave the typos alone so you know I really did type this. But let me know if you see any sentences that make no sense, and I'll clean them up.

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.

DEV Community: clojure

Learning Clojure from Scratch - Make It Yours

Step 1: Look at what the server receives

Step 2: Send back HTML instead of plain text

Step 3: Create a reusable page template

Step 4: Show the right page

Step 5: Handle pages that don't exist

The whole file

Deploy it

If something went wrong

What you learned

Next

Learning Clojure from Scratch - Put It on the Internet

What you need

Why a few things have to change

Step 1: Let the outside world choose the port

Step 2: Bundle it into one file

Step 3: Write the recipe

Step 4: Leave some things out

Step 5: Write some documentation

Step 6: Deploy

If something went wrong

What you learned

Next

Learning Clojure from Scratch - Hello, World

What you need

Create a project folder

Step 1: Tell Clojure about your project

Step 2: Write the program

Piece 1: Define a namespace and require some code

Piece 2: Handle requests

Piece 3: Create a main function and start the server

Run it

Change something

Break it on purpose

If something went wrong

What you learned

Next

Getting Started with Clojure

Introduction

How Clojure code executes

Environment Setup

Using Clojure CLI

Using Leiningen

Language Basics

Quick Reference

Fundamentals

When to use what?

More on Clojure

Understand the Syntax

Atom vs Agent in Clojure

Learning to code a new language with an AI tutor

The app 👨‍💻

I defined the instructions & design first 📐

The instructions

The data model

Filling in the gaps 🧩

Sometimes AI just did it anyway 🙈

What I learned 📚

The training log is gold

Testing server-rendered HTML with hickory instead of substrings

Being able to ask 'why' is really important

TDD worked well

It was (fairly) quick, and I understand it

What didn't work so well 🚧

It was confidently wrong (sometimes)

Green tests, broken page

Its memory went stale

Recommendations ✅

Conclusion

Macro Macros

Graph Queries

Flint

Another Step

Filters and Bindings

Arguments

Macro Macros

Small Issue

Wrap Up

Embabel agents as Clojure data

Testing server-rendered HTML with `hickory` instead of substrings

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