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.
Twenty-one 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!), the fork and the two consequence readers over it (fork,
preview, edit-with-consequences!), the store transfers (import!, export!,
export-text!, and load-foreign!, whose options belong to the reader plugin),
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), and
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.
**Twenty-one 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!`), the fork and the two consequence readers over it (`fork`,
`preview`, `edit-with-consequences!`), the store transfers (`import!`, `export!`,
`export-text!`, and `load-foreign!`, whose options belong to the reader plugin),
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`), and
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 |