The build's switches — the vaelii.* JVM system properties and the VAELII_*
environment variables — read in one place, each against a domain, and refused when
the value is outside it.
This is kb/check-opts!'s invariant one layer out: an option that is not read is not
an option. A switch read as a membership test or an equality against one spelling has
no wrong value — every misspelling falls to the other branch — so under that reading
vaelii.disk.auto-compact=disabled is compaction on and vaelii.disk.fsync=always
is the three-second tick, which is the durability level the operator is trying to
leave. A process that reports itself configured and is not is the failure
check-opts! exists to prevent, on the property that decides whether a crash loses
data. So no switch is read that way here.
truthy and falsy below, case-insensitively, and nothing else: every boolean switch
reads the same words, so a spelling that works on one works on all of them and a
spelling that works on none is an error rather than the opposite setting. A blank
value is unset — an exported-but-empty environment variable is the shell's way of
saying nothing.
Each switch is read once at a door, never on a worker:
check! reads every switch here at kb/open-kb, so a wrong value fails the open —
before a record is written and while what the operator typed is still legible. It
checks the whole set rather than the ones this KB's backend reads, because gating
the check on the configuration is how a wrong value in the configuration escapes it.durability/compact-dead-ratio and compact-min-interval-ms are read per fsync
tick, inside fsync-all's catch Throwable, which logs an exception's class name
and nothing else. A throw there is an unattributable log line repeating every three
seconds with auto-compaction silently dead, which is why the eager check! exists
rather than trusting the reader at its call site.arbitrate-constraints? and web-dev? are read at namespace load, because each
is the root value of a var and a var root cannot be deferred. They refuse there,
naming themselves, for guard/max-body-bytes' reason: a silent fallback leaves an
operator believing a setting they never made, and a raw parse failure out of a def
reports as a namespace that would not load rather than as the typo it is.Five switches name a path or a label with no domain to check — vaelii.disk.dir,
vaelii.kb.path, vaelii.kb.catalog, vaelii.build, vaelii.clingo.lib — and two
name a member of a registry that resolves them itself: vaelii.asp.solver
(asp.solver/configured) and vaelii.llm.provider (llm.provider/configured). The
ceiling VAELII_MAX_BODY_BYTES refuses at guard/max-body-bytes, where both servers
read it.
The build's switches — the `vaelii.*` JVM system properties and the `VAELII_*` environment variables — read in one place, each against a domain, and **refused when the value is outside it**. This is `kb/check-opts!`'s invariant one layer out: *an option that is not read is not an option*. A switch read as a membership test or an equality against one spelling has no wrong value — every misspelling falls to the other branch — so under that reading `vaelii.disk.auto-compact=disabled` is compaction **on** and `vaelii.disk.fsync=always` is the three-second tick, which is the durability level the operator is trying to leave. A process that reports itself configured and is not is the failure `check-opts!` exists to prevent, on the property that decides whether a crash loses data. So no switch is read that way here. ## One vocabulary for the boolean switches `truthy` and `falsy` below, case-insensitively, and nothing else: every boolean switch reads the same words, so a spelling that works on one works on all of them and a spelling that works on none is an error rather than the opposite setting. A blank value is *unset* — an exported-but-empty environment variable is the shell's way of saying nothing. ## Where a refusal lands Each switch is read **once at a door**, never on a worker: - `check!` reads every switch here at `kb/open-kb`, so a wrong value fails the open — before a record is written and while what the operator typed is still legible. It checks the whole set rather than the ones this KB's backend reads, because gating the check on the configuration is how a wrong value in the configuration escapes it. - `durability/compact-dead-ratio` and `compact-min-interval-ms` are read **per fsync tick**, inside `fsync-all`'s `catch Throwable`, which logs an exception's class name and nothing else. A throw there is an unattributable log line repeating every three seconds with auto-compaction silently dead, which is why the eager `check!` exists rather than trusting the reader at its call site. - `arbitrate-constraints?` and `web-dev?` are read at **namespace load**, because each is the root value of a var and a var root cannot be deferred. They refuse there, naming themselves, for `guard/max-body-bytes`' reason: a silent fallback leaves an operator believing a setting they never made, and a raw parse failure out of a `def` reports as a namespace that would not load rather than as the typo it is. ## What is not checkable here Five switches name a path or a label with no domain to check — `vaelii.disk.dir`, `vaelii.kb.path`, `vaelii.kb.catalog`, `vaelii.build`, `vaelii.clingo.lib` — and two name a member of a registry that resolves them itself: `vaelii.asp.solver` (`asp.solver/configured`) and `vaelii.llm.provider` (`llm.provider/configured`). The ceiling `VAELII_MAX_BODY_BYTES` refuses at `guard/max-body-bytes`, where both servers read it.
(arbitrate-constraints?)Does the process default to arbitrating a definitional clash rather than refusing it
(VAELII_ARBITRATE_CONSTRAINTS, default off)? A KB naming a :constraints policy
overrides it.
Does the process default to arbitrating a definitional clash rather than refusing it (`VAELII_ARBITRATE_CONSTRAINTS`, default off)? A KB naming a `:constraints` policy overrides it.
(assertive-arg-types?)Do the argument constraints entail as well as constrain (VAELII_ASSERTIVE_ARG_TYPES,
default off)?
Do the argument constraints entail as well as constrain (`VAELII_ASSERTIVE_ARG_TYPES`, default off)?
(check!)Read every switch once, refusing the first whose value is outside its domain.
kb/open-kb calls it, which is the earliest door that exists for the properties the
durability daemon would otherwise read on a tick.
Every switch and not this KB's: a :memory KB with vaelii.disk.fsync=always set is
a process one directory away from a durability guarantee it does not have, and the
next open is not a better place to hear about it.
Read every switch once, refusing the first whose value is outside its domain. `kb/open-kb` calls it, which is the earliest door that exists for the properties the durability daemon would otherwise read on a tick. Every switch and not this KB's: a `:memory` KB with `vaelii.disk.fsync=always` set is a process one directory away from a durability guarantee it does not have, and the next open is not a better place to hear about it.
(disk-auto-compact?)Is background and opportunistic compaction on (vaelii.disk.auto-compact, default
on)? Read by the fsync tick and by the close path — one knob, not two.
Is background and opportunistic compaction on (`vaelii.disk.auto-compact`, default on)? Read by the fsync tick and by the close path — one knob, not two.
(disk-cache-capacity)Hot records held per kind (vaelii.disk.cache, default 65536; 0 disables the cache).
A count, so it is read at the record store's open rather than at namespace load: a
Long/parseLong in a top-level def turns =64k into a namespace that will not
load, which reports the typo as a broken build.
Hot records held per kind (`vaelii.disk.cache`, default 65536; 0 disables the cache). A count, so it is read at the record store's open rather than at namespace load: a `Long/parseLong` in a top-level `def` turns `=64k` into a namespace that will not load, which reports the typo as a broken build.
(disk-compact-dead-ratio)The dead ratio a log must reach to be worth compacting
(vaelii.disk.compact-dead-ratio, default 0.5). A ratio, so outside 0–1 it is a
threshold that either never fires or fires on every tick.
The dead ratio a log must reach to be worth compacting (`vaelii.disk.compact-dead-ratio`, default 0.5). A ratio, so outside 0–1 it is a threshold that either never fires or fires on every tick.
(disk-compact-min-interval-ms)The floor between two auto-compactions of one backend
(vaelii.disk.compact-min-interval-ms, default 300000).
The floor between two auto-compactions of one backend (`vaelii.disk.compact-min-interval-ms`, default 300000).
(disk-compress)vaelii.disk.compress: :zstd, :lz4, or nil for uncompressed frames (the
default). A case with a nil default arm is what made =gzip and =zstdd read as
no compression at all — a store written smaller than the operator asked for, with
nothing to say so.
`vaelii.disk.compress`: `:zstd`, `:lz4`, or nil for uncompressed frames (the default). A `case` with a nil default arm is what made `=gzip` and `=zstdd` read as no compression at all — a store written smaller than the operator asked for, with nothing to say so.
(disk-fsync-mode)vaelii.disk.fsync: :dsync opens every log rwd, so an append is durable when it
returns; :tick (the default, and what unset means) leaves durability to the
vaelii.disk.sync-ms daemon.
`vaelii.disk.fsync`: `:dsync` opens every log `rwd`, so an append is durable when it returns; `:tick` (the default, and what unset means) leaves durability to the `vaelii.disk.sync-ms` daemon.
(disk-lock?)Is the single-writer FileLock taken when a directory opens (vaelii.disk.lock,
default on)? Off is for a filesystem whose FileLock is unreliable, and it removes
the enforcement rather than the contract.
Is the single-writer `FileLock` taken when a directory opens (`vaelii.disk.lock`, default on)? Off is for a filesystem whose `FileLock` is unreliable, and it removes the enforcement rather than the contract.
(disk-sync-ms)The durability daemon's tick, in milliseconds (vaelii.disk.sync-ms, default 3000;
0 disables the daemon).
The durability daemon's tick, in milliseconds (`vaelii.disk.sync-ms`, default 3000; 0 disables the daemon).
(disk-tokens?)Are sentex bodies written as token ids (vaelii.disk.tokens, default off)? Off
because it is the one part of the record store that adds a durable ground truth, so a
store opts in. Reading is never gated on it — a frame carries its own tag.
Are sentex bodies written as token ids (`vaelii.disk.tokens`, default off)? Off because it is the one part of the record store that adds a durable ground truth, so a store opts in. *Reading* is never gated on it — a frame carries its own tag.
The spellings that mean off. Wider than "false" because the disk switches
document 0 / off / no as well, and removing an accepted spelling breaks a setup
that works.
The spellings that mean **off**. Wider than `"false"` because the disk switches document `0` / `off` / `no` as well, and removing an accepted spelling breaks a setup that works.
(index-snapshot?)Is the mapped index image written and read (vaelii.index.snapshot, default off)?
index-snapshot/enabled? is what call sites read — it adds the platform guard.
Is the mapped index image written and read (`vaelii.index.snapshot`, default off)? `index-snapshot/enabled?` is what call sites read — it adds the platform guard.
(prop-bool nm default)nm as a boolean, default when unset. Anything outside truthy / falsy is
refused rather than read as the falsy branch, which is where =disabled meaning
enabled came from.
`nm` as a boolean, `default` when unset. Anything outside `truthy` / `falsy` is refused rather than read as the falsy branch, which is where `=disabled` meaning *enabled* came from.
(prop-double nm default lo hi)nm as a double, default when unset, bounded by lo/hi as prop-long is.
`nm` as a double, `default` when unset, bounded by `lo`/`hi` as `prop-long` is.
(prop-enum nm accepted default want)nm as the value accepted maps its (lower-cased) spelling to, default when unset.
want is the prose the refusal offers instead — a roster alone answers what is
legal and not what the legal one does, and the second is what the operator who
typed the wrong one needs.
`nm` as the value `accepted` maps its (lower-cased) spelling to, `default` when unset. `want` is the prose the refusal offers instead — a roster alone answers *what is legal* and not *what the legal one does*, and the second is what the operator who typed the wrong one needs.
(prop-long nm default lo hi)nm as a long, default when unset. lo/hi bound it — every count read here is a
duration or a capacity, so one below zero is a typo rather than a setting.
`nm` as a long, `default` when unset. `lo`/`hi` bound it — every count read here is a duration or a capacity, so one below zero is a typo rather than a setting.
The spellings that mean on, for every boolean switch. One vocabulary rather than
one per switch: a word that works for one switch works for all of them, so nothing is
learned about vaelii.disk.tokens that is false of vaelii.disk.auto-compact.
The spellings that mean **on**, for every boolean switch. One vocabulary rather than one per switch: a word that works for one switch works for all of them, so nothing is learned about `vaelii.disk.tokens` that is false of `vaelii.disk.auto-compact`.
(web-dev?)Is the browser a development server (VAELII_DEV, default off)? A value, not mere
presence: VAELII_DEV=0 says off and read as presence it said on.
Is the browser a development server (`VAELII_DEV`, default off)? A value, not mere presence: `VAELII_DEV=0` says off and read as presence it said on.
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 |