vaelii.impl.gloss — com.vaelii/vaelii 0.1.0

A sentence in English, composed from what the KB already says about its own vocabulary rather than generated.

The read path is the one with no verifier. Nothing in the engine can say that an English sentence describing (genl penguin bird) is wrong, so a fluent gloss is a way to teach a reader something false through their only window onto the formal content — which makes reading the more dangerous direction here, not the safer one. The defence is to not write prose at all where the KB has already written it.

The comment is the template

The vocabulary documents itself: every shipped predicate carries a comment sentex, and those comments are written in a shape that is already a template —

(comment eats "(eats ?animal ?food) means that ?animal takes ?food as nourishment. …")
(comment genl "(genl ?subtype ?supertype) means that every ?subtype is a ?supertype. …")

a signature naming the argument positions with variables, then a clause saying what the predicate means in those names. So glossing (eats Fido kibble) is not a generation problem: read eats's comment, take its first clause, substitute the actual arguments for the signature's variables.

The variables are why it reads: a parameter spelled ?animal cannot be mistaken for an individual the way Animal can, and because the name carries the sort, the clause after it needs no sortal noun to lean on — so what substitutes is the sentence a reader wants rather than one with place Paris in it. Everything past that first clause is documentation for a reader, not template: how the predicate is used, what it is not, and what the KB does with it.

A signature written with plain capitalized words and a colon — (eats Animal Food): Animal eats Food — is read the same way, since an imported vocabulary spells its own comments and they are not ours to rewrite.

This is why the composer is a lookup and a substitution rather than a table of hand-written patterns: adding a predicate with a documented signature gives it a gloss for free, and a comment edited to say something else changes the gloss with it. Of the 277 shipped comments, 175 carry a signature; the 102 that do not are nouns — 86 types and 16 unit individuals — which need none, because a type gloss is "X is a dog" and the comment is the apposition after it.

What the composition rate does not measure is whether a gloss is worth reading. It earns its place where the predicate name is opaque — genl glossed as "Every dog is an animal" teaches a reader what genl means — and adds nothing where the predicate is already an English verb.

What it will not do

A term with no comment degrades to naming the term. It does not invent a description, because an invented description is exactly the failure this exists to prevent, and a reader who sees the bare name has lost nothing they were entitled to. Every result carries :source saying which it got:

:composed every literal came from a comment :partial some did; the rest are named :named nothing to compose from — the terms, in a frame :generated a model wrote it (gloss never does this; see with-model)

The formal sentence is never replaced by the gloss — that is the caller's contract, and docs/web.md states it for the browser.

gloss clj

(gloss kb sentence)

sentence in English, composed from the KB's own comments. Never calls a model — the answer is a lookup and a substitution, so a sentence over documented vocabulary costs zero model calls by construction rather than by luck.

Answers {:text :source}; :source is :composed / :partial / :named as described in the namespace docstring. A caller must render the formal sentence alongside.

readable clj

(readable kb sx)

The gloss of a stored sentex, with its sentence read back in the author's own variable names — the shape a reader recognizes, rather than the canonical ?var0 the store keeps.

template clj

(template text)

A comment read as a template: {:params ["?subtype" "?supertype"] :text "every ?subtype is a ?supertype"}, or {:text …} alone when the comment describes rather than parameterizes.

A signature's parameters must be plain words or variables. (totalDuration (list I1 I2 …) D) names a compound argument, and substituting into it would need to know that (list …) is one argument rather than three — so it is read as a description instead, which loses the substitution and keeps the honesty.

term-words clj

(term-words t)

A term as it reads in prose. A snake_case type is de-spelled — underscores become spaces — because physical_object is one word written with a typographic convention and not a description of anything; nothing else is touched, and a variable reads as its own letter. The formal sentence sits beside every gloss, so a reader who wants the symbol has it.

text clj

(text kb sentence)

The gloss as one sentence-cased line, which is what a page renders.

with-model clj

(with-model kb sentence ask)

gloss, falling back to ask for a sentence the KB documents nothing about.

Deliberately a separate entry point rather than a branch inside gloss: the guarantee worth having is that the ordinary path cannot reach a model at all, and a guarantee that depends on an argument being nil is not one. The fallback fires only on :named — a partially composed gloss keeps what the KB actually said rather than handing the whole sentence to a model that would rewrite the documented half too.

The result is marked :generated, and a caller must render that distinctly: the reader is entitled to know which they are reading.