Persistence facade: the backend table, connection lifecycle, and every
delegated store-*/db-* fn.
SQLite is the backend Vis ships and the default; backends is the closed
table a second dialect would join. The facade dispatches each delegated call
by resolving the matching var on the chosen backend namespace
((ns-resolve ns-sym 'db-store-iteration!) etc.) and applying it to the
original args. This keeps the facade dialect-agnostic - every migration
runner / driver-specific oddity stays inside the backend adapter.
Frontends still call db-error->user-message here, but the actual
translation is offered by backend adapters. Same for store-staleness
checks used by the process-wide shared connection.
Persistence facade: the backend table, connection lifecycle, and every delegated `store-*`/`db-*` fn. SQLite is the backend Vis ships and the default; `backends` is the closed table a second dialect would join. The facade dispatches each delegated call by resolving the matching var on the chosen backend namespace (`(ns-resolve ns-sym 'db-store-iteration!)` etc.) and applying it to the original args. This keeps the facade dialect-agnostic - every migration runner / driver-specific oddity stays inside the backend adapter. Frontends still call `db-error->user-message` here, but the actual translation is offered by backend adapters. Same for store-staleness checks used by the process-wide shared connection.
(->json m)Serialize a value to a JSON TEXT column. Nil in, nil out.
Serialize a value to a JSON TEXT column. Nil in, nil out.
(->kw v)Keyword/string -> TEXT, stripping the leading colon. Nil -> nil.
Keyword/string -> TEXT, stripping the leading colon. Nil -> nil.
(->ref v)Normalize an entity reference to a string ID for SQL. Accepts: UUID, string, or nil. Returns string or nil.
The ONLY way to extract a SQL-ready string from an entity reference -- pass the plain UUID or string directly.
Normalize an entity reference to a string ID for SQL. Accepts: UUID, string, or nil. Returns string or nil. The ONLY way to extract a SQL-ready string from an entity reference -- pass the plain UUID or string directly.
(<-json s)Parse a JSON TEXT column. STRINGS-ONLY: keys come back as VERBATIM STRINGS -
no :key-fn keyword re-keywordizing. Whatever needs an internal keyword
shape converts at ONE named adapter, never here.
Parse a JSON TEXT column. STRINGS-ONLY: keys come back as VERBATIM STRINGS - no `:key-fn keyword` re-keywordizing. Whatever needs an internal keyword shape converts at ONE named adapter, never here.
(bound-error-data error)Bound every string inside a structured terminal error, at any depth. Pure; nil in, nil out.
Bound every string inside a structured terminal error, at any depth. Pure; nil in, nil out.
(bounded-error-text s)(bounded-error-text s max-chars)Truncate ONE diagnostic string so the result NEVER exceeds max-chars,
naming what was cut. A string already within the cap comes back identical, so
a normal error is persisted byte for byte.
Truncate ONE diagnostic string so the result NEVER exceeds `max-chars`, naming what was cut. A string already within the cap comes back identical, so a normal error is persisted byte for byte.
(db-adopt-and-reorder-project-sessions! db-info project-id session-ids)(db-create-connection! db-spec)Open a persistence connection from db-spec.
Common spec forms: nil - no DB (returns nil) :memory - in-memory ephemeral store (backend-defined) "path/to.db" - file-backed store (backend-defined) {:backend :sqlite :path ...} - explicit backend selection {:backend :sqlite :datasource ds} - caller-owned DataSource
Omitting :backend selects default-backend; the facade tags the returned
store map with the chosen backend so all subsequent facade calls dispatch
correctly.
Open a persistence connection from `db-spec`.
Common spec forms:
nil - no DB (returns nil)
:memory - in-memory ephemeral store (backend-defined)
"path/to.db" - file-backed store (backend-defined)
{:backend :sqlite :path ...} - explicit backend selection
{:backend :sqlite :datasource ds} - caller-owned DataSource
Omitting `:backend` selects `default-backend`; the facade tags the returned
store map with the chosen backend so all subsequent facade calls dispatch
correctly.(db-dispose-shared-connection!)Close the shared connection if one is open. Idempotent.
Close the shared connection if one is open. Idempotent.
(db-error->user-message e)Translate a persistence exception into something a human can act on.
Backend adapters own backend-specific recognition; unknown errors fall
back to (ex-message e).
Translate a persistence exception into something a human can act on. Backend adapters own backend-specific recognition; unknown errors fall back to `(ex-message e)`.
(db-get-session-prompt-cache-state db-info session-state-id)(db-list-iteration-attachments-meta db-info iteration-id)(db-list-iterations-attachments-meta db-info iteration-ids)(db-search db-info query opts)Backend-neutral full-text search facade. Delegates to the registered
persistence backend, which RENDERS the neutral query DSL into its native
full-text query and runs it. No caller passes an engine dialect — only the
DSL in search-query-dsl-doc.
query is the DSL — a string (implicit-AND of its words) or a DSL map.
opts:
:owner-table restrict to one owner table (string)
:field restrict to one indexed field (string)
:limit max hits (backend default applies when nil)
Returns a vector of hits sorted by relevance (best first), each
{:owner-table :owner-id :field :snippet :rank}. Backends MUST honor the
DSL; an engine that cannot express a node should degrade it (e.g. :near ->
:all), never reject well-formed DSL. A MALFORMED query (e.g. a lone :not)
may throw — that is a DSL logic error, distinct from un-matchable content.
Backend-neutral full-text search facade. Delegates to the registered
persistence backend, which RENDERS the neutral query DSL into its native
full-text query and runs it. No caller passes an engine dialect — only the
DSL in `search-query-dsl-doc`.
`query` is the DSL — a string (implicit-AND of its words) or a DSL map.
`opts`:
:owner-table restrict to one owner table (string)
:field restrict to one indexed field (string)
:limit max hits (backend default applies when nil)
Returns a vector of hits sorted by relevance (best first), each
`{:owner-table :owner-id :field :snippet :rank}`. Backends MUST honor the
DSL; an engine that cannot express a node should degrade it (e.g. :near ->
:all), never reject well-formed DSL. A MALFORMED query (e.g. a lone :not)
may throw — that is a DSL logic error, distinct from un-matchable content.(db-session-state-list-for-workspace db-info workspace-id)(db-session-state-set-workspace! db-info session-state-id workspace-id)(db-session-turn-stats db-info)(db-session-turn-stats db-info session-id)Per-session turn aggregates. 1-arity: the whole store, {soul-id-str {:turn-count n :latest-turn-at Date}}. 2-arity: ONE session's stats
unwrapped (nil when unknown), so a single-session read never scans the
whole store.
Per-session turn aggregates. 1-arity: the whole store, `{soul-id-str
{:turn-count n :latest-turn-at Date}}`. 2-arity: ONE session's stats
unwrapped (nil when unknown), so a single-session read never scans the
whole store.(db-set-session-prompt-cache-state! db-info session-state-id state)(db-set-turn-attachment-transcription! db-info
session-turn-soul-id
position
transcription)(db-shared-connection! db-spec)Return the process-wide shared persistence connection for db-spec,
opening it on first call and caching the handle for the lifetime of
the JVM. Subsequent calls return the cached handle regardless of
the db-spec argument - the singleton intentionally pins to the
first spec it saw.
Pair with db-dispose-shared-connection! on process shutdown.
Return the process-wide shared persistence connection for `db-spec`, opening it on first call and caching the handle for the lifetime of the JVM. Subsequent calls return the cached handle regardless of the `db-spec` argument - the singleton intentionally pins to the first spec it saw. Pair with `db-dispose-shared-connection!` on process shutdown.
(db-store-iteration! db-info opts)Same delegating shape as the macro-defined fns, but with input validation kept here so every backend gets the same precondition guarantees for free.
Same delegating shape as the macro-defined fns, but with input validation kept here so every backend gets the same precondition guarantees for free.
(db-update-session-turn! db-info session-turn-id opts)Write a turn's terminal outcome. Same delegating shape as the macro-defined
fns, with the DIAGNOSTIC text bound here so every backend gets the same
guarantee for free: the write that records HOW a turn ended can never be lost
to an unbounded error message (see max-persisted-error-chars).
Write a turn's terminal outcome. Same delegating shape as the macro-defined fns, with the DIAGNOSTIC text bound here so every backend gets the same guarantee for free: the write that records HOW a turn ended can never be lost to an unbounded error message (see [[max-persisted-error-chars]]).
(db-workspace-list-by-repo db-info repo-id)(db-workspace-list-by-repo db-info repo-id state-set)The backend a spec/store without an explicit :backend dispatches to.
The backend a spec/store without an explicit `:backend` dispatches to.
Hard cap on ONE persisted DIAGNOSTIC string (256K chars).
SQLite refuses any bound value over SQLITE_MAX_LENGTH (1e9 bytes) with
[SQLITE_TOOBIG], and the value carrying a turn's terminal error is the one
most likely to be unbounded: a runtime message can quote the entire document
that broke it. An error is a DIAGNOSTIC, so a truncated head is worth
strictly more than the lost turn an oversized one costs. An answer's own
content and the CTX snapshot are DATA and are never truncated here -- an
oversized one degrades through the caller's outcome guard instead.
Hard cap on ONE persisted DIAGNOSTIC string (256K chars). SQLite refuses any bound value over `SQLITE_MAX_LENGTH` (1e9 bytes) with `[SQLITE_TOOBIG]`, and the value carrying a turn's terminal error is the one most likely to be unbounded: a runtime message can quote the entire document that broke it. An error is a DIAGNOSTIC, so a truncated head is worth strictly more than the lost turn an oversized one costs. An answer's own content and the CTX snapshot are DATA and are never truncated here -- an oversized one degrades through the caller's outcome guard instead.
(normalize-status status)Map runtime status keywords to the schema CHECK constraint values. Allowed: running, done, error, interrupted.
Map runtime status keywords to the schema CHECK constraint values. Allowed: running, done, error, interrupted.
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 |