vaelii.browser.web — com.vaelii/vaelii 0.31.0

A small reitit-ring web browser over a KB:

/ the upper ontology (contexts, types, core predicates, disjointness) /stats KB-wide counts, contexts by size, and the reasoning-health ledgers /find?q=<pattern> the terms whose name matches, from the index's term-name set /term?q=<term> every sentex containing the term, grouped by the index root that reaches it (functor / argument-position / context / term-index) /sentex/:id a sentex (literal or rule): its belief state (IN, or the why-not reason — superseded / defeated / unsupported), supports, dependents /justification/:id a justification: its supports (arguments) and dependent sentex /levels?q=<goal> the lookup-to-query stack: what each of the 8 levels answers /edit the multi-sentex editor (GET seeds it, POST saves) — a fragment /{term,find,levels}/rows one more page of a capped list, as bare rows

Run it with lein run -m vaelii.browser.web (serves a starter-loaded KB on :3000). Handlers are pure request -> response, so they are testable without a server.

Every page is answered twice over: as a whole document, and — when htmx asks, which is every navigation and search — as the #main fragment that actually lands. What a page costs in KB reads is part of what this demonstrates, since the browser reads the public surface alone and each read is a round-trip under --attach; see the render-env section below and docs/web.md.

->form clj

(->form s)

Read a ?q= / ?ctx= query param as EDN, or nil when it is not readable. Every route that takes a term or a goal parses through this, since a URL may carry (. It catches Throwable, not Exception, because a deeply nested form overflows the reader's stack with a StackOverflowError, which would escape as a 500.

-main clj

(-main & args)

Serve the browser.

lein run -m vaelii.browser.web ; a fresh starter-loaded in-process KB lein run -m vaelii.browser.web --port 8080 lein run -m vaelii.browser.web --listen 0.0.0.0 ; reachable off-machine (opt-in) lein run -m vaelii.browser.web --attach HOST PORT [WEBPORT]

--attach renders the KB a running daemon (vaelii.host.serve) owns over the API (docs/operations.md). The bind decides the requirement (guard/require-token!):

• a non-loopback --listen address ⇒ VAELII_API_TOKEN is required, presented as Authorization: Bearer <token>; without one it is a stderr line and exit 2;
• Loopback, the default, needs no token.

The KB it starts on is registered with the catalog and made active, so it appears in /kbs as entry number one.

app clj

(app target)

The ring handler for a KB. Pure request -> response. target is what each page reads: a KB, a remote access (v/remote), or a holder, a deref-able yielding either (vaelii.browser.catalog/holder). Every handler resolves the holder per request, so activating another entry re-points the browser without rebuilding the handler. This is the routing half; handler adds the Host allowlist, and a test drives app directly.

assert-page clj

(assert-page env)

(assert-page {:keys [kb sandbox] :as env} state result)

The new-sentex page: the form, and — after a save — what it stored.

assert-post clj

(assert-post {:keys [kb sandbox] :as env}
             {:keys [text ctx monotonic?] :as state})

Assert what the new-sentex form holds: read the lines, check them all against the KB, and only when every one is admissible apply them in one edit. Nothing partial is written. A form addressed to the session's sandbox before it exists opens it first, once the lines have read cleanly and before they are checked, since the checks are context-scoped and a sandbox with no genlCx edge sees none of the shipped vocabulary. When the check then refuses the form, the edge is taken out again (sandbox/reset! over the empty extent). A form past sandbox/max-sentexes is refused :over-ceiling before the sandbox is opened.

completions-page clj

(completions-page {:keys [kb] :as env} q)

The terms a prefix could become, as the list the editor drops under the caret: a v/find-terms prefix match, so a keystroke costs the size of the vocabulary, each hit carrying its role colour. A blank prefix, and one past complete-q-cap, answer nothing, since the route is reachable per keystroke and through the daemon.

consequences clj

(consequences {:keys [kb] :as env} heading batch)

The consequence panel for batch ({:add [[sentence context] …] :remove [handle …]}) over the render env's KB: v/preview capped at preview-max-results per group, rendered under heading. A read — preview stores nothing and hands the KB back at the same handles — but it asserts and rolls back to get there, so a route calling it is a writer for the duration (an extension's :write route).

current clj

(current target)

The KB a request reads. A holder (anything deref-able — vaelii.browser.catalog/holder) yields whichever KB is active right now; a KB or an access value is itself. Every handler goes through here, which is what lets the browser switch KBs under a running server.

default-page clj

(default-page {:keys [kb types] :as env})

demo-apply clj

(demo-apply kb sandbox op first-h)

Do one step's write, and answer the first-handle to carry forward. Split from the rendering because the page is built from a render env taken after the write (step 1 creates the sandbox). Both adding steps open the sandbox first: without its genlCx edge it sees no shipped context, so CxBiology's flight rule would derive nothing.

demo-page clj

(demo-page env)

(demo-page env first-h)

(demo-page {:keys [sandbox] :as env} first-h returned?)

The walkthrough: the script, the evidence for the conclusion under test, the next button, and what the KB currently holds about Pingu. Everything on it is read back out of the KB after the write, so the page cannot claim a state the engine is not in.

dev-repl clj

(dev-repl)

Start the browser for a REPL session and hand the prompt straight back.

What lein browser calls, and the only thing project.clj names. Port from VAELII_WEB_PORT, else 3000 — the same read -main does; loopback only. A port already in use is reported, not thrown — you asked for a REPL and you get one either way, which is the difference between a busy port being an inconvenience and being a failed startup. A refusal to release the earlier starter leaves the running server up.

dev-stop clj

(dev-stop)

Stop the server dev-repl started. No !: it takes down a socket, not knowledge — the KB is untouched and still at the prompt.

edit-preview-post clj

(edit-preview-post {:keys [kb] :as env} handles text)

What this save would do, without doing it: the same diff edit-post computes, read through v/preview, so it can run on a pause in the typing. A form that does not read is reported here too, and a named handle that holds no sentex is reported as the save would refuse it. The heading counts a changed handle as retracted only when retraction-plan says it goes; the plan reads the KB before the save's own adds.

find-page clj

(find-page {:keys [kb] :as env} q)

Term search over the KB's vocabulary: list every term whose name matches q, each linking to its term page. q reads as re-find does (a bare dog finds every term containing it, ^parent anchors) and filters the index's term-name set. A pattern that resolves to a single term jumps to that term's page, because it is the only match or names a term exactly; the jump sets HX-Push-Url. An unusable pattern or an empty query reports gently.

find-rows-page clj

(find-rows-page {:keys [kb] :as env} q offset)

One more page of search hits — what the result list's continuation sentinel fetches.

fresh-starter-kb! clj

(fresh-starter-kb!)

(fresh-starter-kb! opts)

A KB freshly loaded with the starter ontology. Flushes the record + index stores first, so a repeated run (or one over data from an earlier code version) starts from a clean, deterministic state rather than re-asserting over stale handles. For a persistent KB, construct one and call core/recover instead.

front-rows-page clj

(front-rows-page env section offset)

One more page of a front-page list.

funnel-page clj

(funnel-page {:keys [kb] :as env})

Every forward rule and what chaining did with it — placed, refused (and why), or silent — ranked by what is wrong (funnel-ranked), one page of cards at a time. A run form on 32's job registry populates it live.

funnel-rows-page clj

(funnel-rows-page {:keys [kb] :as env} offset)

One more page of the funnel — what its continuation sentinel fetches.

handler clj

(handler target)

(handler target {:keys [host] :or {host loopback}})

What the browser actually serves: app behind the Host allowlist.

inference-page clj

(inference-page {:keys [kb] :as env} goal ctx depth)

The search stepped through — a goal, a context and a depth in; the tree the node engine builds out, plus the same goal raced across tacticians. Sits beside /levels: a goal typed at either is answerable at both.

A depth is required (the node engine's termination is the bound and nothing else), so the form always carries one. A malformed goal, or one the search cannot run, is rendered rather than thrown — the page has no exception middleware.

justification-page clj

(justification-page {:keys [kb] :as env} jid)

kbs-load clj

(kbs-load id params)

Start loading source id with the options the form submitted. An id the catalog holds no source for reaches load-source all the same, so its :unknown-source refusal — which names the ids there are — is the note kbs-post puts on the page. A dir is refused unless catalog/request-paths? (refuse-a-named-dir!).

kbs-page clj

(kbs-page env)

(kbs-page env note)

The knowledge bases page: what is loaded, and what can be. note is what the catalog said about the action that led here — a refusal is a state to show, not an error status, since the page is still the right answer.

kbs-post clj

(kbs-post act make-env)

Perform a catalog action and answer with the page it changed.

The render env is built after the action, not before: activating changes which KB the page reads, and rendering the one it was reading a moment ago would show the switch as not having happened. What the catalog refuses — a second concurrent load, a source already loaded, an entry whose loader has not yet stopped — comes back as a note on the page.

levels-page clj

(levels-page {:keys [kb] :as env} goal ctx)

The lookup-to-query stack over a goal: what each of the eight levels answers, so the level at which results first appear is the mechanism the answer depends on. With no goal, the stack itself.

A vector goal is the conjunctive query prove takes, and the levels do not take one — they answer about a literal. So a conjunction gets the join plan and stops there, rather than being rendered through eight sections that cannot address it.

levels-rows-page clj

(levels-rows-page env goal ctx lvl offset)

One more page of results for a single level — what a level's continuation sentinel fetches.

local-kb clj

(local-kb env)

The in-process KB behind env, or nil when the browser reads a remote daemon (--attach). What an extension checks before work that needs the KB in this process — a preview, a write, dozens of reads a round-trip each would make slow.

network-page clj

(network-page {:keys [kb] :as env} ctx calc)

The constraint network a calculus computes over one context: which terms it relates, what still holds of every pair, whether the believed facts are satisfiable at all, and one concrete arrangement consistent with them.

Every calculus is offered whether or not its prover is registered — a network is a property of the stored facts, and add-prover only decides whether ask consults it.

reasoning-page clj

(reasoning-page {:keys [kb sandbox] :as env})

The gallery. The page asks nothing itself: each available card asks its question after the page has loaded, under example-ms (/reasoning/verdict). The ones with premises ask the sandbox once the reader has established them, and show a button until then.

reasoning-run clj

(reasoning-run kb sandbox id)

Establish one example's premises in the sandbox. A write, so a POST — and the sandbox is opened first, exactly as the demo does: without its genlCx edge it would see no shipped rule and the example would quietly derive nothing.

register-extension clj

(register-extension ext-name ext)

File ext under ext-name (a lower-case keyword), replacing any extension of that name, and answer the name. Every key is optional:

:routes [["/ext/<name>/…" {:get f :post f :write f}] …] — each f is (fn [env req] …) answering hiccup (sent as a fragment) or a ring response map. :post is refused cross-origin; :write is a POST that runs under the browser's write guard, with env over the KB the guard judged. :menu [[label "/ext/<name>/…"] …] — links in the menubar. :term-actions (fn [env term] hiccup) — drawn beside the heading of every term page. :term-panel (fn [env term] hiccup) — drawn last on every term page. :on-start (fn []) — run when -main or dev-repl starts the server, before it serves. :stylesheet a classpath resource, served at /ext/<name>.css and linked from every page. :script a classpath resource, served at /ext/<name>.js and loaded (deferred).

render-env clj

(render-env kb req)

What one request's rendering reads that does not vary row to row — built once per request and threaded through every render fn in place of a bare KB.

render-form clj

(render-form env form)

(render-form env form seen)

(render-form env form seen depth)

Render a sentence (or subterm) with every atomic subterm an individually role-colored link, structure shown with parentheses, laid out by layout. A form spanning lines is wrapped in .sx-rule, which keeps its newlines and indent. A (sentexHandle N) subterm renders as the sentence N holds, linked, on every surface that prints a meta-sentex (a term-page row, the sentex page, a preview's excepts line).

retract-post clj

(retract-post {:keys [kb] :as env} handles)

Retract the named handles through edit: one settle for the batch, the write path the editor's save takes. The answer deletes every row that is gone out of band, the named handles and whatever the sweep took. The write follows the check-edit round-trip every write post makes (docs/operations.md), so a stale handle comes back as the problem panel.

sentex-page clj

(sentex-page {:keys [kb] :as env} h)

start clj

(start target {:keys [port host] :or {port 3000 host loopback} :as opts})

Start a Jetty server for target (a KB, an access value, or a catalog holder). Returns the server (non-blocking). :host defaults to loopback; pass an address ("0.0.0.0") to bind publicly, which requires a token: :token, or VAELII_API_TOKEN when the key is absent, as -main requires it (guard/require-token!). It serves app as built: a reload does not reach it (dev-repl is the server that follows one), and :reload? is refused. .stop drops every /op feed subscription (ending-feeds-on-stop).

start-profiler clj

(start-profiler)

Start the sampling profiler's UI when the operator asked for one (VAELII_PROFILER) and the class resolves. A no-op otherwise, and a logged line when the operator asked and it is absent. The claim is a compare-and-set! onto ::starting, so a namespace reload and two concurrent callers cannot start a second one; a failed start restores the state. Bare, not !: it starts a server and destroys nothing. Both entry points call it.

stats-page clj

(stats-page env)

(stats-page env note)

(stats-page {:keys [kb types] :as env} note clashes? nogoods?)

KB-wide statistics: the headline counts (contexts, types, stored sentexes, the placed nogoods and the filed violations), what the last chaining run did and a control to run another, a contexts-by-size table, and the filed ledger of dropped derivations (filed-violations) when non-empty. A page load reads no belief and fetches no record. clashes? asks the standing disjointness question and nogoods? the contradictions the placed nogoods come to (nogoods-section); each is computed, so neither runs unasked. The held facts and rules and the convicted firings are a button that runs a job (held-section). note is what a just-finished forward-chaining run reported.

stats-rows-page clj

(stats-rows-page {:keys [kb] :as env} section offset)

One more page of a stats-page list — what its scroll sentinel fetches. Every section is recomputed rather than carried: each is a function of the KB, so a continuation asks the same question the page asked and gets the same order.

stored-sentexes clj

(stored-sentexes {:keys [kb] :as env} result)

What a write stored, as the assert form shows it: a row per stored sentex, then the callout of what followed from them (derived-callout). result is v/edit-with-consequences!'s answer.

stylesheet-resource clj

The browser's stylesheet, on the classpath (resources/public/vaelii.css).

term-link clj

(term-link env t)

(term-link env t seen)

A role-colored link to a term's page (variables are not links; a reified term is its expression — nat-ref).

term-page clj

(term-page {:keys [kb] :as env} term)

A term's page: the concept graph, the three type lines, the sentexes grouped by the index root that reaches them, and what a registered extension adds: actions beside the heading (extension-term-actions) and panels at the foot (extension-panels). The page lists what the KB was told (the index groups) and draws position (the graph) instead of restating a closure in prose; vaelii.core/describe answers all six readings (docs/api.md). Each part has its own budget: the index groups in rows (group-cap), root extents deferred to a reveal (group-sentexes), and the graph in reads (graph-side-budget).

term-rows-page clj

(term-rows-page {:keys [kb] :as env} term g offset)

One more page of rows for index group g of term — what a group's continuation sentinel fetches. The groups are recomputed and indexed the same way the page built them, so g names the same group it did then.

tree-rows-page clj

(tree-rows-page env pred node offset)

One node's children, as bare rows — what a disclosure fetches when it is opened, and what its show more sentinel fetches to extend it.

unregister-extension clj

(unregister-extension ext-name)

Take the extension filed under ext-name out of the browser; its routes, panel and assets are gone from the next request. Answers the name.

why-page clj

(why-page {:keys [kb] :as env} h)

The whole proof tree for a handle — vaelii.core/why rendered, collapsible. Linked from the sentex page, which shows only the first hop.