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 door 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.
Eleven publics that take an option map are outside it, and instrumenting says
nothing about their arguments: the batch writes (assert-many,
bulk-assert-facts!), the fork and the two consequence readers over it (fork,
preview, edit-with-consequences!), the store transfers (import!, export!),
and check, abduce, kb-quality, clear-caches. A roster 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 door 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.
**Eleven publics that take an option map are outside it**, and instrumenting says
nothing about their arguments: the batch writes (`assert-many`,
`bulk-assert-facts!`), the fork and the two consequence readers over it (`fork`,
`preview`, `edit-with-consequences!`), the store transfers (`import!`, `export!`),
and `check`, `abduce`, `kb-quality`, `clear-caches`. A roster 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 eleven opts-taking publics it does not reach are named in
this namespace's docstring and pinned 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 eleven opts-taking publics it does **not** reach are named in this namespace's docstring and pinned 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 |