Graphden documentation

Graphden — AI author context

You are editing a Graphden graph through the MCP tools. This document teaches you the entity model and the conventions, so your proposals read like the graph a human would have written. Read it before your first mutation.

This is not CLAUDE.md (which is for developers working on graphden itself). This teaches you to write user fn-defs.


1. The one idea

Code is a graph in a database, not text in files. You do not write Clojure. You compose existing functions by declaring data:

{:name :add-tax
 :parent :mul
 :args {:nums [{:as :amount} {:value 1.2}]}}

That is a complete program. :add-tax inherits :mul’s single :nums list slot, pins the second entry of that list to 1.2, and leaves the first entry open as a free arg named :amount — so :add-tax is “multiply your :amount by 1.2”, callable as a one-argument function. There is no function body to write; there is only which function you build on and what you bind.

2. Two kinds of fn

Kind Shape You write these?
base-fn wraps ONE Clojure/Java call; has an implementation No — they’re primitives (:add, :if, :str, :map, :get, :http-request, :pg-query, …)
composed fn (fn-def) :parent (or :parents) + :args; NO implementation Yes — this is all you write

You never write a base-fn. If you find yourself wishing for “a function that does X in one step”, the answer is almost always to compose existing base-fns, not to ask for a new primitive.

3. The fn-def map — every key

{:name       :my-fn            ; keyword, unique per (namespace, name). Omit → anonymous (rare; you want names).
 :namespace  "app.orders"      ; optional dotted string; groups fns. Omit → top level.
 :parent     :base-or-fn       ; inherit this fn's slots. (or :parents [:a :b] for two axes — rare)
 :args       {:slot-name ...}  ; bind / customise inherited slots (see §4)
 :description "one line"}       ; optional but kind — shows in the editor

:return-type, :effects, refinement/type-row keys exist too, but for composition you rarely set them: they are inferred from what you build on. Bind slots; let the type checker compute the rest.

4. :args — binding slots

A slot is a named input a parent exposes. In :args, the KEY is the slot name; the VALUE says how to fill it:

You want Write Example
a literal value the value directly {:status 200}, {:port 8080}
a reference to another fn its :name keyword {:handler :my-router}
a literal keyword (not a ref) {:value :kw} {:tag {:value :active}}
rename the slot as it surfaces {:as :new-name} {:x {:as :price}}
leave it OPEN (a free arg) omit the key entirely —
append to an inherited LIST slot a vector, or {:append [items]} {:nums [3]} — the parent’s items stay, yours follow
make an inherited optional slot required from here down {:required true} {:end {:required true}} (one-way: never false again below)
seal a still-free slot against descendants {:terminal true} {:end {:terminal true}} — descendants may not bind it
close a list against descendants {:append [items] :closed true} {:nums {:append [1 2] :closed true}} — descendants may not append

The reference trap (this is why you write EDN, not JSON): a bare keyword in a value position is a reference to another fn. :my-router means “wire in the fn named :my-router”. If you actually want the literal keyword :active as data, you must write {:value :active}. JSON cannot express this difference — that is exactly why the upsert-fn-defs tool takes EDN text.

A rename needs a NAMED fn-def. {:x {:as :price}} lifts the new name to the fn-def that carries it; an inline anonymous map ({:parent :foo :args {:x {:as :price}}} in a value position) does not lift it any further. When a slot must surface under a new name, give that step a :name (a _-private one is fine).

5. Slots, inheritance, free args

So “make a specialised version of X” = “inherit X, bind the slots you want fixed, leave the rest free”. That is the whole mechanism.

A value an ancestor set is final. You cannot re-bind a slot your parent (or any ancestor) already bound to a value or a fn — the write is refused (value-override), by the editor, the API and upsert-fn-defs alike. Want a different value? Inherit from a fn that leaves the slot free (the base, a sibling) and bind it there. The same refusal guards a slot an ancestor sealed with :terminal true (terminal-seal) and a list an ancestor closed with :closed true (list-closed). Lists are otherwise the one thing you EXTEND rather than override: appending to an inherited list keeps the ancestor’s items in front of yours.

;; :add sums a sequence in its :nums slot.
{:name :add-10 :parent :add :args {:nums [10]}}
;; add-10 seeds :nums with [10]; a caller extends the sequence.

6. Control flow is data too

There is no if-statement; there is the :if base-fn, and you bind its slots:

{:name :fee-for
 :parent :if
 :args {:test :is-premium?      ; a ref to a predicate fn
        :then {:value 0}
        :else {:value 5}}}

:cond, :and, :or, :map, :filter, :try work the same way — they are base-fns whose slots you fill. Wrapping a literal value so it can be referenced is :const ({:parent :const :args {:value …}}).

Bind :else even when it is nothing — :else nil. An unbound :else is an unbound slot, so it surfaces as a free arg named else on your fn and on everything that composes it (a :do you meant to run as a service would be refused for having a free arg). describe-fn shows the free-arg list; an unexpected else there is this.

7. Your workflow (the tools)

  1. list-namespaces — see the shape of the graph.
  2. search-fns / read-fn / describe-fn — learn the vocabulary. search-fns matches names first and descriptions last, so a concept you can describe but not name still lands. Before you compose on :parent :foo, read-fn “foo”: it returns the fn and everything it reaches AS fns.edn — the same EDN you write back, so read it as a worked example of the slots and their bindings (format: "rows" gives the raw storage rows instead). Compose on what exists; don’t invent parents. After you compose, describe-fn your fn: it returns the COMPUTED contract — free args (what execute-fn will accept), the start-blocking subset, effects, return type, whether the fn is service-eligible, and unread-bindings — a binding you wrote on a slot that every reader already binds closer (closer-fn-wins), so your value is silently ignored: rebind it on the fn that actually reads the slot, or drop it. A leaked slot, a missing effect or an unread binding all show up before you run anything.
  3. create-branch — ALWAYS, before any mutation. Name it for the task, e.g. ai/add-order-total. main is the human’s; you work on a branch and never touch main.
  4. upsert-fn-defs — write your fn-defs (EDN vector) INTO that branch. The same constraints a human faces apply (no dependency cycles, unique names, type-check), so a rejection is precise feedback — read it, fix the proposal, try again. Platform fn-defs (the ones the package sync owns) are refused — build under your own namespace.
  5. execute-fn — run what you built and check the result. When the result is not what you expected — especially a silent nil — run it again with trace: true: the answer then carries the call tree the run actually walked, one row per fn invoked. A step of your composition that never appears there ran nothing; that is where to look. Every read tool takes an optional branch, so you never need to switch headers to look at your own branch.
  6. run-tests — after writing tests (§10), run the branch’s test set and read {total passed failed} — the write→verify loop, closed. (The platform’s own self-tests — core.tests, web.tests, … — are skipped unless you pass platform?: true; they are not yours.)
  7. diff-branch — this is what the human reviews: added / modified / removed entities. Leave your branch clean and readable. (list-branches re-orients you after a context loss.)

8. Naming & style (so your graph reads like ours)

9. Effects — what the cloud will and won’t run

On the hosted platform, the organization’s tier bounds your graph’s effects. The anonymous demo allows graph DB operations, time, randomness and in-graph state. Registered free and paid tiers also allow metered, egress-guarded network access (including HTTP and the organization’s own external database); persistent processes require the dedicated tier. Environment variables, local files and raw SQL on the platform database remain blocked for tenant graphs. Discover the available primitives and compose within your tier’s budget; a different composition cannot bypass the runtime effect gate.

10. Tests — pin your invariants in the graph

A test is an ordinary fn in a namespace whose dotted path contains the segment tests (myproj.tests); it passes when it runs without a throw. Compose :assert-eq (:actual = a ref to the fn under test with inputs pinned, :expected = a literal) or :assert (truthy check). Bind ALL free args — tests run with no arguments. The name IS the label: slugify-keeps-dashes, not test-1. Pure tests re-run automatically when anything in their dependency closure changes; effectful ones only via the Run buttons / POST /api/tests/run. After you build or change a fn, add or update its tests in the same session — a green suite is how the human you co-edit with trusts your change.

11. A complete worked example

Goal: “an order total = sum of line items, plus 20% tax”.

[{:name :subtotal
  :namespace "app.orders"
  :parent :add
  :description "Sum the :nums line-item sequence."}
 {:name :with-tax
  :namespace "app.orders"
  :parent :mul
  :args {:nums [{:as :amount} {:value 1.2}]}
  :description "Multiply :amount by 1.2 (20% tax)."}
 {:name :order-total
  :namespace "app.orders"
  :parent :with-tax
  :args {:amount :subtotal}
  :description "Line-item subtotal, taxed."}]

Then execute-fn "order-total" {:nums [10 20 30]} → 72.0 (subtotal 10+20+30 = 60, then × 1.2). diff-branch shows three fns added-in-target; the human reviews and merges.


Remember: you are not writing code that graphden runs — you are describing, as data, how existing functions compose. Every rejection is the type system or the constraint checker telling you the composition doesn’t hold yet. Read it, adjust the data, propose again.