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, a daemon thread factory and the caches: a bounded memo, an identity-checked cache, one memo scope for work at one moment, such as a context render, and a time-limited cache that can refresh in the background.
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). The caches are the one exception: they change the atoms
that their callers pass, and refreshed also keeps the set of computations
that run now. 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, a daemon thread factory and the caches: a bounded memo, an identity-checked cache, one memo scope for work at one moment, such as a context render, and a time-limited cache that can refresh in the background. 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). The caches are the one exception: they change the atoms that their callers pass, and [[refreshed]] also keeps the set of computations that run now. 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.
An atom of key -> [parts value] while with-memo-scope runs, else nil.
An atom of key -> `[parts value]` while [[with-memo-scope]] runs, else nil.
(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.
(bounded-memoize f max-entries max-weight weight-fn)(bounded-memoize f max-entries max-weight weight-fn key-fn)Memoize immutable inputs with entry and weight limits. Evict the oldest entry first.
Compute misses outside cache updates. Concurrent misses can compute more than once.
weight-fn receives the original arguments and result, and estimates retained bytes.
key-fn receives the arguments. Store only its key, not the original arguments.
Keep every input that affects the result in the key.
Memoize immutable inputs with entry and weight limits. Evict the oldest entry first. Compute misses outside cache updates. Concurrent misses can compute more than once. `weight-fn` receives the original arguments and result, and estimates retained bytes. `key-fn` receives the arguments. Store only its key, not the original arguments. Keep every input that affects the result in the key.
(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.
(cached cache limit k parts f)The value of (f) kept in cache, an atom of key -> [parts value].
Reuse the value of k while each item of the parts vector is identical? to the
stored one. A new but equal input computes again, without a deep compare. Put every
input of f in k or parts. Nil and false are kept too; a failure is not.
A new key empties the map first when it already holds limit keys. Reset cache
to {} to forget every value. f runs outside the atom update, so concurrent
misses can compute more than once.
The value of `(f)` kept in `cache`, an atom of key -> `[parts value]`.
Reuse the value of `k` while each item of the `parts` vector is `identical?` to the
stored one. A new but equal input computes again, without a deep compare. Put every
input of `f` in `k` or `parts`. Nil and false are kept too; a failure is not.
A new key empties the map first when it already holds `limit` keys. Reset `cache`
to `{}` to forget every value. `f` runs outside the atom update, so concurrent
misses can compute more than once.(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.
(constant-time=? a b)Timing-safe comparison for secret strings. Plain = stops at the first byte that
differs, so response timing would leak a token's length and prefix.
MessageDigest/isEqual compares in constant time. A nil never matches.
Timing-safe comparison for secret strings. Plain `=` stops at the first byte that differs, so response timing would leak a token's length and prefix. `MessageDigest/isEqual` compares in constant time. A nil never matches.
(content-str x)pr-str of x with every element and level, for digests and stored text.
Each process caps *print-length* and *print-level* for its logs. Under these
caps, two collections that differ after the cap print the same text.
`pr-str` of `x` with every element and level, for digests and stored text. Each process caps `*print-length*` and `*print-level*` for its logs. Under these caps, two collections that differ after the cap print the same text.
(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.
(deadline-ms secs)The now-ms instant secs seconds from now.
The [[now-ms]] instant `secs` seconds from now.
(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.
(poll deadline interval-ms f)Call f every interval-ms until it answers a reduced value or deadline passes.
Answer the reduced value, or the last answer of f at the deadline. No sleep goes past
the deadline. An interrupt ends the wait with InterruptedException.
Call `f` every `interval-ms` until it answers a `reduced` value or `deadline` passes. Answer the reduced value, or the last answer of `f` at the deadline. No sleep goes past the deadline. An interrupt ends the wait with `InterruptedException`.
(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.
(refreshed cache ttl-ms k f wait?)The value of (f) kept in cache as in ttl-cached, without a wait while a value
exists. After ttl-ms, return the old value and compute the next one on a future, one
at a time for each cache and key. A failure keeps the old value. For a key without a
value, compute it on this thread when wait?, else start the future and return nil.
The value of `(f)` kept in `cache` as in [[ttl-cached]], without a wait while a value exists. After `ttl-ms`, return the old value and compute the next one on a future, one at a time for each cache and key. A failure keeps the old value. For a key without a value, compute it on this thread when `wait?`, else start the future and return nil.
(scope-cached k parts f)(f), kept for k and parts as in cached inside with-memo-scope, else
computed on each call.
`(f)`, kept for `k` and `parts` as in [[cached]] inside [[with-memo-scope]], else computed on each call.
(seconds-left deadline)Whole seconds until deadline, rounded up. Answers 0 once it has passed.
Whole seconds until `deadline`, rounded up. Answers 0 once it has passed.
(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.
(string-chars value)The characters of every string inside value, a cheap retained-size weight for
bounded-memoize.
The characters of every string inside `value`, a cheap retained-size weight for [[bounded-memoize]].
(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.
(ttl-cached cache ttl-ms k f)The value of (f) kept in cache, an atom of key -> [expires-at value].
Reuse the value of k until ttl-ms milliseconds after f returned it. Nil and false
are kept too; a failure is not. Reset cache to {} to forget every value, or dissoc
a key to forget one. f runs outside the atom update, so concurrent misses can compute
more than once.
The value of `(f)` kept in `cache`, an atom of key -> `[expires-at value]`.
Reuse the value of `k` until `ttl-ms` milliseconds after `f` returned it. Nil and false
are kept too; a failure is not. Reset `cache` to `{}` to forget every value, or dissoc
a key to forget one. `f` runs outside the atom update, so concurrent misses can compute
more than once.(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.
(with-memo-scope & body)Run body in one memo scope, where scope-cached computes each key once. Use it for
work that reads its inputs at one moment, such as one context render. An outer scope
stays in force. Bind *memo-scope* to nil inside it for a fresh read.
Run `body` in one memo scope, where [[scope-cached]] computes each key once. Use it for work that reads its inputs at one moment, such as one context render. An outer scope stays in force. Bind [[*memo-scope*]] to nil inside it for a fresh read.
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 |