The engine's one shared leaf: the primitives every namespace kept re-rolling — a millisecond clock, the two blank-string idioms, a trimmed environment read, UTF-8 bytes, SHA-256, HMAC-SHA256, secure random bytes, unpadded base64url, byte concatenation, the hex fold, compact JWS signing and a daemon thread factory.
It requires NOTHING from the rest of vis and never will. That is the whole
contract: a leaf can be required from anywhere — specs that load during
namespace initialization, the gateway, the sandbox — without a cycle to
reason about. Everything here is a pure function of its arguments (or of one
process-wide reading), so no reading here may become a top-level value: a
def that CALLS one freezes the BUILDER's answer into the native image
(native-image-env-capture-test is the gate).
A name earns a place here when a THIRD namespace needs it. A helper with one caller belongs beside its caller, not in this file.
The engine's one shared leaf: the primitives every namespace kept re-rolling — a millisecond clock, the two blank-string idioms, a trimmed environment read, UTF-8 bytes, SHA-256, HMAC-SHA256, secure random bytes, unpadded base64url, byte concatenation, the hex fold, compact JWS signing and a daemon thread factory. It requires NOTHING from the rest of vis and never will. That is the whole contract: a leaf can be required from anywhere — specs that load during namespace initialization, the gateway, the sandbox — without a cycle to reason about. Everything here is a pure function of its arguments (or of one process-wide reading), so no reading here may become a top-level value: a `def` that CALLS one freezes the BUILDER's answer into the native image (`native-image-env-capture-test` is the gate). A name earns a place here when a THIRD namespace needs it. A helper with one caller belongs beside its caller, not in this file.
(base64url b)Unpadded base64url text of b, the form of JWT parts, PKCE values, Web Push
keys and URL-safe secrets.
Unpadded base64url text of `b`, the form of JWT parts, PKCE values, Web Push keys and URL-safe secrets.
(bytes->hex b)Lowercase hex of b, two characters per byte and no separators.
Lowercase hex of `b`, two characters per byte and no separators.
(compact-jws key header claims)The compact JWS header.claims.signature (RFC 7515) of the JSON texts header
and claims. The key selects the algorithm: a P-256 EC key signs ES256 and an
RSA key signs RS256. The alg of header must name the same algorithm.
The compact JWS `header.claims.signature` (RFC 7515) of the JSON texts `header` and `claims`. The key selects the algorithm: a P-256 EC key signs ES256 and an RSA key signs RS256. The `alg` of `header` must name the same algorithm.
(concat-bytes & arrays)One array with the bytes of each array in arrays, in order.
One array with the bytes of each array in `arrays`, in order.
(daemon-thread-factory prefix)A thread factory for a background executor. Its threads are daemons, so they
never keep the process alive. Their names are prefix-1, prefix-2 and so
on, so a thread dump names the owner.
A thread factory for a background executor. Its threads are daemons, so they never keep the process alive. Their names are `prefix-1`, `prefix-2` and so on, so a thread dump names the owner.
(env-val k)Environment variable k, trimmed, or nil when it is unset or blank.
Environment variable `k`, trimmed, or nil when it is unset or blank.
(fence-delimiter body)Markdown fence delimiter (a backtick run) longer than any backtick run in
body. Arbitrary content — a file being read, a diff of a Markdown file, a
tool's stdout — carries Markdown fences of its own; a fixed triple-backtick
wrapper is then ambiguous and the INNER fence closes the outer block early,
so everything after it renders as prose instead of code. CommonMark permits
longer fences: pick the shortest safe one.
Markdown fence delimiter (a backtick run) longer than any backtick run in `body`. Arbitrary content — a file being read, a diff of a Markdown file, a tool's stdout — carries Markdown fences of its own; a fixed triple-backtick wrapper is then ambiguous and the INNER fence closes the outer block early, so everything after it renders as prose instead of code. CommonMark permits longer fences: pick the shortest safe one.
(fenced body)(fenced body lang)Wrap body in a fenced code block body itself cannot close early, with an
optional lang info string. Callers keep their own blank/nil guards.
Wrap `body` in a fenced code block `body` itself cannot close early, with an optional `lang` info string. Callers keep their own blank/nil guards.
(hmac-sha256 key data)HMAC-SHA256 of data with key — the one MAC that webhook signatures and
Web Push key derivation share.
HMAC-SHA256 of `data` with `key` — the one MAC that webhook signatures and Web Push key derivation share.
(json-str value)Encode raw data with Charred's default escaping and object conversion. Gateway payloads still use contract.wire/json-str for canonical key/value shapes.
Write directly to the in-memory sink: Charred's convenience function wraps it in a BufferedWriter, allocating an unnecessary 16 KiB buffer for every message.
Encode raw data with Charred's default escaping and object conversion. Gateway payloads still use contract.wire/json-str for canonical key/value shapes. Write directly to the in-memory sink: Charred's convenience function wraps it in a BufferedWriter, allocating an unnecessary 16 KiB buffer for every message.
(native-image?)True when this is the compiled binary rather than a JVM run.
The two runtimes differ in what they may ASSUME - a spawn argv, a memory
floor, a timeout - so the question is asked in several unrelated places and
answered here once. imagecode is set at build time as well, so a caller
that must tell BUILD from RUNTIME reads the property itself.
True when this is the compiled binary rather than a JVM run. The two runtimes differ in what they may ASSUME - a spawn argv, a memory floor, a timeout - so the question is asked in several unrelated places and answered here once. `imagecode` is set at build time as well, so a caller that must tell BUILD from RUNTIME reads the property itself.
(non-blank x)x trimmed to a string, or nil when it is nil, empty or all whitespace.
`x` trimmed to a string, or nil when it is nil, empty or all whitespace.
(non-blank-string? x)True when x is a string carrying something other than whitespace.
True when `x` is a string carrying something other than whitespace.
(normalize-thinking-text text)Canonical thinking text for every surface — gateway SSE, poll/replay, session transcript and the TUI timeline all normalize HERE so no consumer is the first place a difference appears.
Reasoning streams arrive with paragraph-style blank-line runs and whitespace-padded blank rows; collapse those, then drop the provider's elision marker. nil when nothing is left, so a blank tick falls back to the text already on screen instead of wiping it.
Canonical thinking text for every surface — gateway SSE, poll/replay, session transcript and the TUI timeline all normalize HERE so no consumer is the first place a difference appears. Reasoning streams arrive with paragraph-style blank-line runs and whitespace-padded blank rows; collapse those, then drop the provider's elision marker. nil when nothing is left, so a blank tick falls back to the text already on screen instead of wiping it.
(now-ms)Milliseconds since the epoch — the engine's one wall clock.
Milliseconds since the epoch — the engine's one wall clock.
(random-bytes n)n cryptographically random bytes for secrets, nonces and OAuth state. Each
call uses a fresh SecureRandom, so no generator becomes a top-level value
that the native image could freeze.
`n` cryptographically random bytes for secrets, nonces and OAuth state. Each call uses a fresh `SecureRandom`, so no generator becomes a top-level value that the native image could freeze.
(redact-secret-text text)(redact-secret-text text known-secrets)Redact labelled credentials, credential headers/URLs, private PEM keys and embedded vault handles in PRESENTATION text. This is not a detector for arbitrary unlabelled or encoded secrets. Raw tool values must not pass here.
Optional known-secrets are literal values local to one form validation, not
a registry. Replace them in one pass, longest first, preserving redaction
markers so repeated presentation/sink passes are idempotent.
Redact labelled credentials, credential headers/URLs, private PEM keys and embedded vault handles in PRESENTATION text. This is not a detector for arbitrary unlabelled or encoded secrets. Raw tool values must not pass here. Optional `known-secrets` are literal values local to one form validation, not a registry. Replace them in one pass, longest first, preserving redaction markers so repeated presentation/sink passes are idempotent.
(secret-key? key)Whether a named data key denotes credentials. Non-name keys are not secrets.
Whether a named data key denotes credentials. Non-name keys are not secrets.
One CLOSED sentence or clause end in model text — ., !, ? or … with
any trailing quotes/brackets, at whitespace or end of string, or a newline.
Owned here because the gateway uses it to flush the live stream one sentence
at a time (gateway.state/sentence-closed-in-suffix?). Settled reasoning also
treats a syntactically closed Markdown heading as a complete thought.
One CLOSED sentence or clause end in model text — `.`, `!`, `?` or `…` with any trailing quotes/brackets, at whitespace or end of string, or a newline. Owned here because the gateway uses it to flush the live stream one sentence at a time (`gateway.state/sentence-closed-in-suffix?`). Settled reasoning also treats a syntactically closed Markdown heading as a complete thought.
(settled-thinking-text text)Canonical thinking text for a SETTLED iteration — what a transcript, a timeline entry or a replayed row keeps — or nil when the provider showed nothing usable.
normalize-thinking-text, CLIPPED to the last complete thought: a closed
sentence/line or a syntactically closed Markdown heading; nil when it closed
none. Anthropic writes the thinking summary with a SECOND model that streams
alongside the thinking block; when the block closes first the summary stops
wherever it stood — mid-word — and the wire terminates it with the … marker.
So prose AFTER the last complete boundary is exactly what the summarizer was
writing when it was cut. A closed heading, however, is a complete structural
unit and remains useful without terminal punctuation.
LIVE ticks keep normalize-thinking-text: mid-stream every summary is still
a fragment, and the stream must paint as it arrives. This decision belongs at
the shared progress boundary; presentation clients render its settled value
exactly rather than maintaining their own filtering vocabulary.
Canonical thinking text for a SETTLED iteration — what a transcript, a timeline entry or a replayed row keeps — or nil when the provider showed nothing usable. `normalize-thinking-text`, CLIPPED to the last complete thought: a closed sentence/line or a syntactically closed Markdown heading; nil when it closed none. Anthropic writes the thinking summary with a SECOND model that streams alongside the thinking block; when the block closes first the summary stops wherever it stood — mid-word — and the wire terminates it with the `…` marker. So prose AFTER the last complete boundary is exactly what the summarizer was writing when it was cut. A closed heading, however, is a complete structural unit and remains useful without terminal punctuation. LIVE ticks keep `normalize-thinking-text`: mid-stream every summary is still a fragment, and the stream must paint as it arrives. This decision belongs at the shared progress boundary; presentation clients render its settled value exactly rather than maintaining their own filtering vocabulary.
(sha256-digest)A fresh SHA-256 MessageDigest — for the streaming case, where the content
arrives in chunks and sha256 would need it all in memory at once.
A fresh SHA-256 `MessageDigest` — for the streaming case, where the content arrives in chunks and `sha256` would need it all in memory at once.
(sha256-hex x)Lowercase-hex SHA-256 of bytes, or of a string's UTF-8 bytes — the ONE content-identity fold in the engine: cache keys, replay dedup, source markers and pairing all read the same digits for the same input.
Lowercase-hex SHA-256 of bytes, or of a string's UTF-8 bytes — the ONE content-identity fold in the engine: cache keys, replay dedup, source markers and pairing all read the same digits for the same input.
(strip-elision-marker text)Reasoning text without its trailing provider elision marker.
Suffix-only, therefore MONOTONE: a live stream may strip on every tick and the cumulative-minus-emitted-length delta math still never loses a character.
Reasoning `text` without its trailing provider elision marker. Suffix-only, therefore MONOTONE: a live stream may strip on every tick and the cumulative-minus-emitted-length delta math still never loses a character.
(truncate s n)Head-clip s to at most n chars (no ellipsis) — the engine's ONE head-clip,
so it is also the one place that must never hand a lone surrogate to a UTF-8
consumer downstream (JSON escape, SQLite, the mobile client): a cut that would
land inside an astral char takes one char less instead of splitting the pair.
Head-clip `s` to at most `n` chars (no ellipsis) — the engine's ONE head-clip, so it is also the one place that must never hand a lone surrogate to a UTF-8 consumer downstream (JSON escape, SQLite, the mobile client): a cut that would land inside an astral char takes one char less instead of splitting the pair.
(utf8 s)s as UTF-8 bytes — the one charset every vis wire format names.
`s` as UTF-8 bytes — the one charset every vis wire format names.
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 |