Opt-in clojure.spec contracts for the public vaelii.core API.
The engine already validates the content of what it stores — naming invariants,
well-formedness, disjointness (vaelii.impl.naming / vaelii.impl.wff). These
specs guard the other side: the shape of the arguments a caller passes, the
option and budget maps especially, so a typo like {:strength :monotone} or a
string where a millisecond count belongs is rejected at the entry point with a spec
explanation rather than surfacing as a downstream error.
Nothing here runs unless a caller opts in with
(clojure.spec.test.alpha/instrument public-syms) — instrumentation is a
dev/test tool, so shipping the specs costs a populated registry and no more. They
double as machine-checked documentation and as generators for property tests.
The s/fdefs name their targets by fully-qualified symbol, so loading this
namespace does not load vaelii.core — the specs register against the public var
names, which are the stable contract, independent of how the implementation is
split across vaelii.impl.*.
Coverage is the single-item shape-carrying surface: every entry point that
takes a handle, a context, a level or a strength/direction, together with the
option and budget maps those entry points carry. The pure taxonomy reads
(genls, context-up, …) are specced too, since a wrong-arity call to one of
them is exactly the kind of mistake instrumentation should surface early.
Thirty-two publics that take an option map are outside it, and instrumenting says
nothing about their arguments: the batch writes (assert-many, bulk-assert-facts!,
edit!, replace-facts!), the term operations (rename-terms!, merge-terms!,
copy-terms, remove-terms! and each one-term form), the fork and the two consequence
readers over it (fork, preview, edit-with-consequences!), the store transfers
(import!, export!, export-text!, load-text!, and load-foreign!, whose options
belong to the reader plugin), the batch digest read (digests), the two search-back
reads (search-tree, compare-tacticians) and the truncation report (query-status),
the evaluatable-prover registration (add-evaluatable), the four-valued epistemic-status
read (argue), the two clash reports, whose one option leaves their grounds off
(conflicts, contradictions), and check, abduce, kb-quality, clear-caches.
A test in
vaelii.spec-test holds that list against vaelii.core's own arglists, so the
gap is a set somebody has to edit rather than a claim that goes stale in silence:
a public that grows an option map, or arrives with one, fails that test until it
is either specced here or named there.
Opt-in `clojure.spec` contracts for the public `vaelii.core` API.
The engine already validates the *content* of what it stores — naming invariants,
well-formedness, disjointness (`vaelii.impl.naming` / `vaelii.impl.wff`). These
specs guard the other side: the *shape* of the arguments a caller passes, the
option and budget maps especially, so a typo like `{:strength :monotone}` or a
string where a millisecond count belongs is rejected at the entry point with a spec
explanation rather than surfacing as a downstream error.
Nothing here runs unless a caller opts in with
`(clojure.spec.test.alpha/instrument public-syms)` — instrumentation is a
dev/test tool, so shipping the specs costs a populated registry and no more. They
double as machine-checked documentation and as generators for property tests.
The `s/fdef`s name their targets by fully-qualified symbol, so loading this
namespace does not load `vaelii.core` — the specs register against the public var
names, which are the stable contract, independent of how the implementation is
split across `vaelii.impl.*`.
Coverage is the **single-item** shape-carrying surface: every entry point that
takes a handle, a context, a level or a strength/direction, together with the
option and budget maps those entry points carry. The pure taxonomy reads
(`genls`, `context-up`, …) are specced too, since a wrong-arity call to one of
them is exactly the kind of mistake instrumentation should surface early.
**Thirty-two publics that take an option map are outside it**, and instrumenting says
nothing about their arguments: the batch writes (`assert-many`, `bulk-assert-facts!`,
`edit!`, `replace-facts!`), the term operations (`rename-terms!`, `merge-terms!`,
`copy-terms`, `remove-terms!` and each one-term form), the fork and the two consequence
readers over it (`fork`, `preview`, `edit-with-consequences!`), the store transfers
(`import!`, `export!`, `export-text!`, `load-text!`, and `load-foreign!`, whose options
belong to the reader plugin), the batch digest read (`digests`), the two search-back
reads (`search-tree`, `compare-tacticians`) and the truncation report (`query-status`),
the evaluatable-prover registration (`add-evaluatable`), the four-valued epistemic-status
read (`argue`), the two clash reports, whose one option leaves their grounds off
(`conflicts`, `contradictions`), and `check`, `abduce`, `kb-quality`, `clear-caches`.
A test in
`vaelii.spec-test` holds that list against `vaelii.core`'s own arglists, so the
gap is a set somebody has to edit rather than a claim that goes stale in silence:
a public that grows an option map, or arrives with one, fails that test until it
is either specced here or named there.The fully-qualified symbols the s/fdefs above cover — pass to
clojure.spec.test.alpha/instrument / unstrument. This is the single-item
shape-carrying surface: everything that takes a handle, context, level, strength
or direction, the option and budget maps those carry, plus the taxonomy and
equality reads. The eighteen opts-taking publics it does not reach are named in
this namespace's docstring and asserted by vaelii.spec-test.
The fully-qualified symbols the `s/fdef`s above cover — pass to `clojure.spec.test.alpha/instrument` / `unstrument`. This is the single-item shape-carrying surface: everything that takes a handle, context, level, strength or direction, the option and budget maps those carry, plus the taxonomy and equality reads. The eighteen opts-taking publics it does **not** reach are named in this namespace's docstring and asserted by `vaelii.spec-test`.
cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |