vaelii.host.cli — com.vaelii/vaelii 0.24.0

A command-line driver for a KB — the shell dual of the in-process API, launched with lein run -m vaelii.host.cli <cmd> <args…>. It runs the engine in-process (no daemon); to talk to a running daemon use vaelii.host.client instead.

lein run -m vaelii.host.cli assert '(dog Muffet)' CxNaturalWorld --dir /tmp/kb lein run -m vaelii.host.cli query '(dog ?x)' CxNaturalWorld --dir /tmp/kb lein run -m vaelii.host.cli why 3 --dir /tmp/kb lein run -m vaelii.host.cli export /tmp/dump --dir /tmp/kb lein run -m vaelii.host.cli repl --starter # interactive, starter schema lein cli help # every command and what it takes

help is a word rather than only a flag because Leiningen answers lein cli --help itself, printing the alias expansion — the flag never reaches this namespace through the alias, though it does through the full lein run -m vaelii.host.cli --help.

Backend. --dir <path> opens the store there under the backend its files were written by (v/store-backend), or a new durable :disk-log store when it holds none — recovered on open, so a fact asserted in one invocation is there in the next. A --dir whose parent does not exist is refused (open-kb-from) rather than created. upgrade opens a store, brings its reasoning image and index image up to this build, and closes it (upgrade!); --verify recovers anyway and compares the two images. With no --dir the KB is in-memory and lives only for the process — useful for repl or a single compound session, pointless across one-shot commands. --starter loads the shipped schema (types, contexts, relation rules) so you can explore the ontology. --strength monotonic marks an assert or assert-rule known-true. export takes --variant records|records+index and --compression gzip|xz|none.

A flag belongs to the commands that read it (command-flags), and one carried by a command that does not is refused rather than dropped — those three are the driver's and go anywhere, the rest do not. A value it cannot honour is refused on the same argument: --format texr and --depth twice name nothing.

stdout is the answer. err! keeps a refusal off it, and on-stderr keeps the engine's own log lines off it too — Trove's console backend prints to *out*, which here is what a script redirects. A refusal is one stderr line, error: [<:type>] <message> (refusal-line), so a script branches on the keyword and not on the prose.

One writer. A --dir KB takes the single-writer file lock (docs/storage.md), so the CLI and a daemon cannot own the same directory at once — by design. diff and upgrade open no KB of the run's (without-a-kb), so diff answers beside a daemon that holds --dir.

-main clj

(-main & argv)

Run one command (run) and leave with its exit status.

check-args! clj

(check-args! cmd args opts)

Refuse what dispatch refuses of a command line without reading a KB: the operand count (check-arity!), a whole-number flag's value (count-option), --nearest beside a handle, and an export --format that names nothing or comes with a dump's flags.

-main asks this before it opens the KB, so a refused line leaves no --dir store behind, and --starter loads nothing for it; dispatch asks it again, for the lines a REPL session runs over the KB it already holds. args are data, as dispatch takes them.

check-arity! clj

(check-arity! cmd args)

Refuse a command line with the wrong number of operands, naming what the command takes and what it got.

Without this the short line reaches dispatch, whose nth raises IndexOutOfBoundsException — caught and printed, so lein cli assert '(dog Rex)' answers error: IndexOutOfBoundsException: a true statement about a vector, and no help at all to someone who left off a context. A long line is refused too, since the extra operand is otherwise dropped in silence — and a dropped context is a fact stored somewhere other than where it was meant to go.

check-flags! clj

(check-flags! cmd opts)

Refuse a flag cmd does not read, naming what it does read.

-main calls this rather than dispatch, and that placement is the whole of it: the REPL reuses one option map for every line it runs, so a session opened --strength monotonic must not have a later match line refused for carrying the session's flag. The line naming repl is checked against the union instead, and the lines inside it against nothing.

An unknown command word is left alone, as check-arity! leaves it — -main reports that as :unknown-command, which says more than a flag complaint about a command that does not exist.

command-table clj

Every command word, in the order --help prints it: [min max operands gloss].

max is nil for a command whose last operand is optional. One table rather than two, because the arity a command takes and the arity --help advertises going out of step is how a usage message starts lying — and dispatch reaches into args with nth, so an unchecked short line raises IndexOutOfBoundsException, whose message is the class name and names neither the command nor the argument.

commands clj

The command words dispatch knows, for the usage message and unknown command.

count-option clj

(count-option flag s)

The whole number flag carries, refused by name when its value is not one.

Long/parseLong on the raw string reports For input string: "twice" — one line and exit 1, so no stack trace, but the line names neither the flag nor the command and is java.lang's rather than the engine's. That is the sentence check-arity! exists to stop being printed for an operand count, reached one argument in.

dispatch clj

(dispatch kb cmd args opts)

Run one command against kb and return its result (a handle, a seq of sentences / solutions, a proof tree, …). args are data; opts is the parsed option map.

A command that answers a set answers it sorted (in-content-order): match, query and ask alongside types and contexts, so one KB prints the same output however its knowledge arrived. prove keeps the DFS's order, which is a reading rather than an artifact.

on-stderr clj

(on-stderr f)

A log fn that writes where f does, with *out* bound to *err*.

The refusal is not the only thing that must stay out of the data: the engine's own log! calls go through Trove's console backend, which prints to *out* (docs/operations.md, "Logging") — and *out* here is a script's lein cli match … > answers.edn. Unset, the dial installs nothing and Trove's own backend prints at :info, so an ordinary export (::exported) or a starter load (two ::dropped-conclusion warnings) lands three lines inside the answer with no variable set at all. A wrapper rather than a level: silencing the engine to keep stdout parseable would trade one loss for another, and the daemon and the browser want the lines where they are.

open-kb-from clj

(open-kb-from {:keys [dir starter memory] :as _opts})

Build the KB a run operates on from the parsed opts: :dir → durable disk (recovered), else in-memory — which :memory also names explicitly, so --memory --dir <path> is a contradiction and is refused rather than resolved by a guess. :starter loads the shipped schema.

A --dir whose parent does not exist is refused (:unknown-source, the keyword upgrade! refuses a directory holding no store under), and nothing is created. The store creates every missing component of the path it opens, so a mistyped /var/lib/veelii/kb answered a read with [] at exit 0 — no such fact, where the truth was no such KB — and left an empty store to answer the same way next time. The CLI creates the KB's own directory and nothing above it: an existing directory, empty or holding a store, and an absent one under an existing parent open as they did, which is how a new KB is made from the shell.

parse-opts clj

(parse-opts args)

Split raw args into [positionals opts]. --k v becomes {:k v}, a bare flag (bare-flags) becomes {:flag true}; everything else is a positional, in order.

A value-taking flag with no value is refused (:unknown-option) rather than bound nil: assert … --strength with nothing after it would otherwise store at :default — the exact class the flag was written to escape — and --dir at the end of a line would open the in-memory KB, gone at process exit. A flag the roster does not name is refused the same way.

read-arg clj

(read-arg cmd s)

One argv string as data: the EDN it reads as — a sentence, a context symbol, a handle — and the raw string when it reads as none.

That last case is what a filesystem path is. /var/lib/vaelii is not a symbol (two slashes), so a command taking a path (export, load) would otherwise fail in the reader, before the command it belongs to had been looked at.

One argument is one form. edn/read-string answers the first and drops the rest, so assert '(dog Muffet) (cat Felix)' CxWell stored the dog, printed its handle and exited 0 with nothing said about the cat — a write that did less than the line asked for and reported success. A second form is refused instead (:bad-args, as a wrong operand count is); a string that reads as no form at all — or as none because it is empty — is still the string it already was, which is what a path is.

cmd names the command in the refusal, and is the :op every :bad-args throw carries.

read-forms clj

(read-forms s)

Every EDN form in s, in order — how a REPL line's args ((dog ?x) CxMy) are parsed into data.

refusal-line clj

(refusal-line e)

The line a refusal prints: error: [<:type>] <message>.

The :type is what a caller branches on (docs/troubleshooting.md), and every other surface carries it — the daemon on the wire, the browser as a chip. A shell reads only the line, so the keyword goes on it, in brackets straight after error:, and the message after it is the engine's own words, unchanged. A throwable carrying no :type — a FileNotFoundException, a StackOverflowError — is :internal-error, the class the daemon answers one with, so the bracket is on every refusal line and never empty.

run clj

(run argv)

Parse argv, open the KB, run the command and print its result; return the exit status. With repl (or no command) it drops into the interactive loop.

Every refusal is one line on stderr and exit 1 (refusal-line), naming its :type: a refused flag, operand or --dir, and whatever the engine refused. An unknown command word is exit 2, with the roster and the help pointer after the line.

Everything that needs no KB is answered before one is opened, since opening a --dir KB takes its single-writer lock and may create its store: help, the flag and operand checks (so a refused line leaves no store behind and loads no --starter), and the commands in without-a-kb.

Throwable, not ExceptionInfo: a missing load file raises FileNotFoundException, and a deeply nested EDN argument or load file raises StackOverflowError (the browser's untrusted-EDN reads make the same catch) — a stack trace where the same mistake in engine vocabulary prints one line.

upgrade! clj

(upgrade! dir)

(upgrade! dir {:keys [verify]})

Bring the store in dir up to this build, and report what that took. Opens the store under the backend its files were written by, with :recover? :auto: a reasoning image this build can install is installed, and one written under another image layout, other engine source or other policies is declined, belief is recovered from the records, and the recover writes a new image. Closing the store then writes the index image a rebuilt index leaves due. Returns

{:dir :backend :reasoning :current | :rebuilt | :written | :no-image :image {:format :network :written-at :source} ; the stamp now on disk, :source cut to 12 :index :current | :rewritten | :no-image :verify …} ; with :verify only

:current is an image the open installed and left as it was; :rebuilt is one the open declined and replaced; :written is the first image of a store that held none; :no-image is a backend that keeps none (:disk-log, :disk-columnar). The records are read and never rewritten.

One option changes what happens to an image written under other engine source:

• :verify moves the image to reasoning.prev/ before the open, so the open recovers from the records and writes a new image. Then it compares the two (reasoning-image/compare-images) and deletes the old one. :verify in the result is {:against source :labels :network :state}, or one keyword when the two cannot be compared: :no-previous-image, :no-image, :layout-changed or :records-moved. When the open writes no image, the old one is moved back.

A directory holding no store is refused (:unknown-source) rather than creating an empty one there. ! because the image it replaces cannot be read back.

usage clj

(usage)

The --help text: every command, its operands and a one-line gloss.