vaelii.impl.client — com.vaelii/vaelii 0.13.0

A thin EDN-over-HTTP client for the vaelii daemon (vaelii.impl.serve). Runs no engine: it POSTs {:op :args} and reads the result back, over JDK java.net.http (no dependency — JDK 21 ships it).

Every call threads an explicit connection handle as its first argument — (query conn '(dog ?x) 'Ctx) — the network mirror of vaelii.core's explicit-kb API. A conn from client holds a reusable HttpClient; no socket opens until a call. A daemon reply of {:ok false} becomes an ex-info carrying the daemon's :error and :type, so a remote naming/disjointness refusal surfaces like a local one.

The bearer token rides on the request the daemon requires it on: the conn carries it (VAELII_API_TOKEN unless :token says otherwise) and every call sets one more header on the builder it was already using. No dependency, no client state, and the conn is still a map you can read.

One wrapper per op, and they are generated (vaelii.regen-client, lein regen-client). The daemon's op table is the single source — an op is a vaelii.core fn with the KB supplied — so a wrapper here is that fn's own spelling, bare or !-marked exactly as vaelii.core spells it, at its own arities with kb replaced by conn. It is generated at build time rather than macroexpanded from serve/ops, because requiring the table would pull the engine, jetty and reitit onto the classpath of a namespace whose whole point is not needing them. client_surface_test compares this file against what the generator would write now, so an op added to the daemon fails the suite until the wrapper is written.

abduce clj

(abduce conn goal)

(abduce conn goal context)

(abduce conn goal context opts)

What would have to be true for goal to be provable in context.

abduce-discard! clj

(abduce-discard! conn result)

Discard an abduction's scratch context — every hypothesis in it, and everything they licensed.

add-provenance clj

(add-provenance conn handle m)

Merge m into handle's provenance map (creating it if absent), returning the merged map.

argue clj

(argue conn asent context)

(argue conn asent context opts)

Four-valued epistemic status of a ground assertion.

ask clj

(ask conn goal)

(ask conn goal context)

(ask conn goal context opts)

Answer goal in context with the pluggable prover engine — the stored facts, the taxonomy closures, transitivity, disjointness, the predicate metadata, the evaluables, NAF, arg type inference, and any prover the application added.

ask-within clj

(ask-within conn goal budget)

(ask-within conn goal context budget)

Anytime ask: answer goal in context, but bounded by budget — a map of any of {:max-ms n :max-results n :max-cost <tier>}.

ask? clj

(ask? conn goal)

(ask? conn goal context)

(ask? conn goal context opts)

Is goal answerable via the prover engine? ask's caveats are this one's too — in particular it expands no rule.

assert clj

(assert conn sentence)

(assert conn sentence context)

(assert conn sentence context opts)

Assert sentence in context (default 'CxUniverse) as a JTMS premise: enforce naming, arg, and disjointness constraints, persist, index (trie + term index), mark IN, integrate into the taxonomy / rule index, then forward-chain.

assert! clj deprecated

(assert! conn sentence)

(assert! conn sentence context)

(assert! conn sentence context opts)

Deprecated spelling of assert, which is what vaelii.core calls it. Identical in every other respect. ! means irreversible here (docs/api.md) and an assertion is neither — retract! takes it back — so the wrapper carrying one said the opposite of what the door does.

assert-many clj

(assert-many conn sentences context)

(assert-many conn sentences context opts)

Assert every sentence in sentences (into one shared context, optional shared opts) with belief settled once at the end — the collection form of with-deferred-settle.

assert-rule clj

(assert-rule conn antecedents consequent)

(assert-rule conn antecedents consequent context)

(assert-rule conn antecedents consequent context opts)

Assert a rule (a sentex whose sentence is an implication) in context.

assert-rule! clj deprecated

(assert-rule! conn antecedents consequent)

(assert-rule! conn antecedents consequent context)

(assert-rule! conn antecedents consequent context opts)

Deprecated spelling of assert-rule, which is what vaelii.core calls it. Identical in every other respect; see assert! for why the ! went.

belief-status clj

(belief-status conn handle context)

Explain handle's belief and visibility from context as a deterministic map.

believed clj

(believed conn handles)

The subset of handles raw structural JTMS IN, as a set — in? asked of many handles at once.

believed? clj

(believed? conn handle context)

Is handle JTMS IN after the (except ...) cascade visible from context?

blocked-justifications clj

(blocked-justifications conn)

The ids of the justifications the network currently holds blocked: their rule's exceptWhen exception holds, so the JTMS has ruled them invalid and they confer nothing — even with every antecedent IN (docs/exceptions.md).

caches clj

(caches conn)

What this process is holding beside the stores — every derived structure the engine caches, ranked by entries.

calculi clj

(calculi conn)

The shipped qualitative calculi as data — one map apiece, naming the calculus, the base relations it distinguishes (jointly exhaustive and pairwise disjoint, so exactly one holds of any two terms), the identity it puts on the diagonal, and the predicates it claims.

call clj

(call conn op args)

(call conn op args {:keys [timeout-ms]})

POST {:op op :args args} and return the :result, or throw ex-info on an {:ok false} reply. The low-level entry the convenience fns wrap; use it for an op with no wrapper yet.

opts is {:timeout-ms n} for this call alone, which only the long :poll needs — everything else answers inside the conn's own timeout.

canonical-sentex clj

(canonical-sentex conn sentence context)

The canonical sentex for sentence in context, without storing it — the un-stored counterpart of sentex.

chain-report clj

(chain-report conn)

Per forward rule, what forward chaining did with it — how many firings it placed, how many it refused and why, or whether it did nothing at all.

chain-stats clj

(chain-stats conn)

Chaining-run instrumentation: {:runs n :last {:derived n :truncated? bool}}.

check clj

(check conn sentence)

(check conn sentence context)

(check conn sentence context opts)

Would (assert kb sentence context opts) succeed, and if not, why? Returns a vector of problems — empty when the sentence is admissible — and stores nothing: no sentex, no index entry, no taxonomy edge, no chaining, no settle.

check-edit clj

(check-edit conn batch)

check over a whole edit batch — {:add [[sentence context opts?] …] :remove [handle …]}, the shape edit takes — storing nothing.

clear-caches clj

(clear-caches conn)

(clear-caches conn opts)

Drop every cache that offers a clear, and say what went: {:cleared [{:cache :label :entries}…] :entries total}.

client clj

(client host port)

(client host port {:keys [timeout-ms] :or {timeout-ms 30000} :as opts})

A connection handle to a daemon at host:port (opts: :timeout-ms, default 30000). Holds a reusable HttpClient; no network happens until a call.

:token is the bearer token every call presents. Omitted, it is VAELII_API_TOKEN (guard/api-token) — the same variable the daemon reads, so a client and a daemon in one environment agree without either being configured; an explicit nil sends no Authorization header, which is what an open daemon wants and what a test of the refusal needs.

A key outside those two, and a non-map opts, are refused (:unknown-option) at the shared door every other entry point in this tree runs its options through.

compare-tacticians clj

(compare-tacticians conn goal)

(compare-tacticians conn goal context)

(compare-tacticians conn goal context opts)

Run goal in context under several tacticians — the node engine's search orderings — each to completion, and return one row per tactician: the search it ran, its wall-clock, and its answer set.

conflicts clj

(conflicts conn)

The contradictions the last settle could not satisfy — the reported 'solve result'.

context-down clj

(context-down conn c)

The contexts that inherit from c, reflexively — c plus every context that sees it.

context-up clj

(context-up conn c)

The contexts c inherits from, reflexively — c plus everything it sees via genlCx.

contexts clj

(contexts conn)

Every context currently in the genlCx hierarchy — the nodes of the closure.

contexts-of clj

(contexts-of conn sentence)

The contexts in which sentence is asserted.

contradictions clj

(contradictions conn)

The coexisting pairs the last settle left standing — represented dilemmas, not failures.

count-in-context clj

(count-in-context conn context)

How many sentexes are stored in context — one set-size read, O(1), nothing fetched.

count-with-arg clj

(count-with-arg conn pos term)

How many fact sentexes hold term at argument position pos, as stored — cheap, one O(1) set-size read per predicate declaring an argument at that slot.

count-with-functor clj

(count-with-functor conn pred)

How many fact sentexes with functor pred are stored — one set-size read, O(1).

defeat-class clj

(defeat-class conn handle)

The current defeat-class of a believed handle (:monotonic / :default), or nil when it is OUT — the effective strength of the belief after settling.

dependent-justifications clj

(dependent-justifications conn handle)

Justifications that use handle as an antecedent — what rests on it, which is what an impact analysis before a retract! asks for.

deprecated? clj

(deprecated? conn term)

(deprecated? conn term context)

Did a believed rewriteOf name term the dispreferred side? False for a sameAs or equals member: those merge without retiring either name.

describe clj

(describe conn term)

(describe conn term context)

(describe conn term context opts)

Everything the KB holds about one term, as one map, keyed by the term's own role (term-role) — the read behind "what can I ask about X?".

disjoint-metatypes clj

(disjoint-metatypes conn)

The declared disjoint metatypes — each a type whose member types are pairwise disjoint by (disjointMetatype M).

disjoint? clj

(disjoint? conn a b)

(disjoint? conn a b context)

Are types a and b provably disjoint (via disjoint declarations, closed under genl)? With a context, only declarations and genl edges visible from it count — the vantage every definitional check now judges from.

edit! clj

(edit! conn batch)

Apply a batch of assertions and retractions in one settle.

edit-with-consequences! clj

(edit-with-consequences! conn batch)

(edit-with-consequences! conn batch opts)

edit, plus what the batch turned out to mean — the belief it added and the belief it took away, in preview's entry shapes.

equiv-class clj

(equiv-class conn term)

(equiv-class conn term context)

Every term known equal to term, itself included.

escalate clj

(escalate conn goal)

(escalate conn goal context)

(escalate conn goal context floor)

The cheapest level that answers goal — climb the stack from floor and stop at the first level with results.

explain-levels clj

(explain-levels conn goal)

(explain-levels conn goal context)

What every level yields for goal: a seq of {:level :name :count}.

export! clj

(export! conn dir)

(export! conn dir opts)

Write kb out as a portable export dump in dir and return a summary:

exposed-clashes clj

(exposed-clashes conn)

Every disjointness clash the KB currently makes jointly visible: a term holding two types some context can see as disjoint, where each membership was admissible where it was written.

find-sentexes clj

(find-sentexes conn term)

Every stored sentex that contains term anywhere (any position, any nesting).

find-terms clj

(find-terms conn q)

(find-terms conn q opts)

The vocabulary terms whose name matches q, sorted by name.

forward-chain clj

(forward-chain conn)

(forward-chain conn opts)

Run forward chaining to a fixpoint over every believed sentex, then settle belief (resolve contradictions).

genl? clj

(genl? conn sub super)

(genl? conn sub super context)

Is sub a (reflexive-transitive) subtype of super? Types, not individuals — for an individual's type membership use isa?.

genls clj

(genls conn t)

(genls conn t context)

The supertypes of type t, reflexively — t itself plus everything reachable from it by genl.

handle-of clj

(handle-of conn sentence context)

The handle of the sentex already storing sentence in context, or nil.

handles clj

(handles conn)

Every live sentex handle in the KB — premises and anything forward-derived alike, read straight off the record store.

has-prop? clj

(has-prop? conn kind pred)

(has-prop? conn kind pred context)

Does pred carry the metadata property kind — one of :transitive, :symmetric, :asymmetric, :reflexive, :functional, :decontextualized, :forced-decontextualized, :abducible, :reifiable, :unreifiable? Declared by the corresponding sentex, e.g. (symmetric siblingOf).

health clj

(health conn)

The daemon's liveness reply, {:ok true} — a GET, so it needs no op, and the one route a daemon answers without the token (serve/open-routes). The header is sent when the conn holds one all the same: a probe that authenticates where it can is no worse off, and this way one code path builds every request.

in? clj

(in? conn handle)

Is the sentex handle raw structural JTMS IN, before contextual exceptions?

inverse-of clj

(inverse-of conn pred)

(inverse-of conn pred context)

The predicate declared inverse to pred by an (inverse P Q) sentex, or nil.

isa? clj

(isa? conn x t)

(isa? conn x t context)

Is individual x (transitively) of type t? Considers only type memberships visible from context (default: any context).

justification clj

(justification conn jid)

The justification for an id, or nil — nil in, nil out; a non-id is refused (:bad-handle).

kb-diff clj

(kb-diff conn b)

What two KBs disagree about, as content: {:added :removed :moved :belief-changed}.

kb-quality clj

(kb-quality conn)

(kb-quality conn opts)

Seven readings about the knowledge — one map, seven keys, each a distribution rather than a number:

levels clj

(levels conn)

The stack as data: {:level :name :below :adds} per level.

lookup clj

(lookup conn level goal)

(lookup conn level goal context)

Answer goal in context using exactly the machinery of level:

metatype-members clj

(metatype-members conn m)

The member types of disjoint metatype m — the set whose every pair disjoint? holds of, closed under genl.

poll clj

(poll conn token cursor)

(poll conn token cursor opts)

Read a subscription forward from cursor — {:events [...] :cursor n :lagged k}.

opts is {:wait-ms n}, the long poll: the daemon holds the request open that long waiting for the first event. The read timeout is extended to cover it, which is the whole of what a long poll costs this client — no second protocol, no held socket of its own, and nothing about the reply changes.

:lagged is on every reply and is the one field a caller must read: non-zero, the ring dropped that many events before this poll reached them.

possible-relations clj

(possible-relations conn calculus context a b)

The base relations calculus still allows between a and b, given everything believed in context — the set ask checks a goal against, exposed directly.

premise? clj

(premise? conn handle)

Is the sentex at handle a premise — asserted in its own right rather than derived? A premise rests on nothing, so no justification names it as a conclusion and retracting its supports cannot take it OUT; a derived sentex is the other case, and supporting-justifications is what shows why.

preview clj

(preview conn batch)

(preview conn batch opts)

What would this batch do to the KB — without leaving it done.

props clj

(props conn kind)

The set of predicates carrying metadata property kind (see has-prop?).

provable? clj

(provable? conn goal)

(provable? conn goal context)

(provable? conn goal context opts)

Is goal provable in context? Takes the same single-sentence or vector-of- sentences conjunction as prove; a conjunction is provable iff all its conjuncts are, under one consistent binding of their shared variables.

prove clj

(prove conn goal)

(prove conn goal context)

(prove conn goal context opts)

Backward-chain in context with the simple recur DFS prover; returns a vector of solution binding maps.

prove-within clj

(prove-within conn goal budget)

(prove-within conn goal context budget)

Anytime prove: run the depth-first backward chainer over goal (a sentence or a conjunction vector, as prove) in context, bounded by budget — a map of any of {:max-ms n :max-results n :max-depth n :max-term-growth n}.

provenance clj

(provenance conn handle)

The provenance map recorded for handle — {:creator … :created … …} — or nil if none.

qualitative-network clj

(qualitative-network conn calculus context)

The constraint network calculus computes over everything believed and visible in context: every pair of terms its predicates relate, tightened by path consistency to the base relations still possible between them.

qualitative-scenario clj

(qualitative-scenario conn calculus context)

One concrete arrangement consistent with everything believed in context — {[a b] → relation}, one base relation per pair — or nil when the believed facts are unsatisfiable.

qualitative-scenarios clj

(qualitative-scenarios conn calculus context limit)

Up to limit distinct arrangements, as qualitative-scenario renders one.

quality-report clj

(quality-report conn quality)

A kb-quality map as Markdown — the counts first and the capped lists after.

query clj

(query conn goal)

(query conn goal context)

(query conn goal context opts)

Answer goal in context — the front door — as a seq of binding maps ({?x val …}) projected onto the goal's own variables.

query-plan clj

(query-plan conn goal)

(query-plan conn goal context)

How a goal would be answered, at whichever of the two scales the goal has.

query? clj

(query? conn goal)

(query? conn goal context)

(query? conn goal context opts)

Is goal answerable under opts? query, asked for one answer.

readable-sentence clj

(readable-sentence conn sx)

A sentex's sentence with the author's variable names restored — pass a sentex map (from sentex / sentexes-matching).

representative clj

(representative conn term)

(representative conn term context)

The term standing for term's equivalence class — term itself when nothing has merged it, so this is total and never nil.

retract! clj

(retract! conn handle)

Retract premise support for a handle, tear down solely-supported sentexes and justifications (keeping anything re-derivable via other witnesses), and reverse their taxonomy / rule-index effects.

same-class? clj

(same-class? conn a b)

(same-class? conn a b context)

Do a and b denote the same thing? The complement of a provable (different a b): distinct symbols denote distinct individuals until an equality sentex says otherwise.

search-tree clj

(search-tree conn goal)

(search-tree conn goal context)

(search-tree conn goal context opts)

The backward search for goal in context, as data — every node the frontier reached, not only the path that answered.

sees? clj

(sees? conn k y)

Does context k see assertions made in context y? True iff y is in k's genlCx up-closure (reflexively, so a context sees itself).

sentex clj

(sentex conn handle)

The sentex for a handle as a map, or nil.

sentex-count clj

(sentex-count conn)

How many sentexes the KB holds, in total — the count the count-aware trie keeps at its root, so O(1) and nothing fetched.

sentexes-in-context clj

(sentexes-in-context conn context)

(sentexes-in-context conn context opts)

Every stored sentex asserted in context (its extent, rules included) — a defeated or unsupported one included.

sentexes-matching clj

(sentexes-matching conn sentence)

(sentexes-matching conn sentence context)

Believed sentexes matching sentence in context (context defaults to ?ctx).

sentexes-with-arg clj

(sentexes-with-arg conn pos term)

(sentexes-with-arg conn pos term opts)

Every stored fact sentex holding term at 1-based argument position pos — a defeated or unsupported one included.

sentexes-with-functor clj

(sentexes-with-functor conn pred)

(sentexes-with-functor conn pred opts)

Every stored fact sentex whose functor is pred, any arity, either polarity — a defeated or unsupported one included.

settle-stats clj

(settle-stats conn)

Instrumentation for the exceptWhen fixpoint in settle.

specs clj

(specs conn t)

(specs conn t context)

The subtypes of type t, reflexively — t itself plus everything that reaches it by genl.

supporting-justifications clj

(supporting-justifications conn handle)

Justifications that conclude handle (its supporting justifications), in content order — the informant's own sentence, then the antecedent sentences (kb/justification-content-key).

term-count clj

(term-count conn)

How many distinct terms the KB's vocabulary holds — one set-size read, O(1), nothing fetched.

term-expression clj

(term-expression conn term)

The functional expression a reified term denotes — (FruitFn AppleTree) for the constant minted from it — or nil for an ordinary term, and for a reified one whose (termOfUnit K E) map is not believed.

terms clj

(terms conn)

Every term the index is keyed by — the KB's vocabulary: each predicate, individual, type, and context name mentioned by a stored sentex, at any nesting depth.

types clj

(types conn)

Every type currently in the genl hierarchy — the nodes of the closure, i.e. every type named by some believed genl edge.

types-of clj

(types-of conn x)

(types-of conn x context)

The types asserted of individual x — functors of unary sentexes (T x), found via the term index.

unwatch clj

(unwatch conn token)

Drop subscription token; true if there was one. Idempotent.

violations clj

(violations conn)

The definitional constraints a derived conclusion would have broken during the last forward-chaining run, and what a bounded pass did not reach.

vocabulary-audit clj

(vocabulary-audit conn)

Every term CxCore declares in kb, classified — {:enforced [[term why] …] :inert [[term why] …] :unclassified [term …] :retired [term …] :contradicted [term …]}.

watch clj

(watch conn)

(watch conn goal context)

Open a change-feed subscription — {:token t :cursor 0 :max-events n}. With no goal it is every belief change; with one it is the standing query core/watch takes, refused identically (:not-watchable) when the goal is not answerable from a moved region.

watchers clj

(watchers conn)

What the daemon is holding open — one entry per subscription, with its goal, how many events it has been :delivered, and how many are still :pending on its ring. Neither is the reader's position, which lives on the client and is a thing the daemon has no way to know.

why clj

(why conn handle)

(why conn handle opts)

Why does the KB believe handle? A proof tree, as data:

why-not clj

(why-not conn handle)

(why-not conn sentence context)

(why-not conn sentence context opts)

Why does the KB not believe handle? The complement of why, as data: