Persistence facade: the Store protocol, the connection lifecycle and the
guarantees every backend gets before it sees a call.
SQLite is the one backend Vis ships. Its namespace loads on the first store
operation, not with this facade (see sqlite), so commands that never touch
the store skip ~480 ms of JDBC/Hikari/Flyway class loading on a cold JVM.
Every Store op forwards to that backend, which hands the facade its
implementation through store-implementation: a backend missing an op fails
to compile.
Frontends still call db-error->user-message here; the backend owns the
actual translation. Same for the store-staleness check the process-wide
shared connection uses.
Persistence facade: the `Store` protocol, the connection lifecycle and the guarantees every backend gets before it sees a call. SQLite is the one backend Vis ships. Its namespace loads on the first store operation, not with this facade (see `sqlite`), so commands that never touch the store skip ~480 ms of JDBC/Hikari/Flyway class loading on a cold JVM. Every `Store` op forwards to that backend, which hands the facade its implementation through `store-implementation`: a backend missing an op fails to compile. Frontends still call `db-error->user-message` here; the backend owns the actual translation. Same for the store-staleness check the process-wide shared connection uses.
Subagent budget operations of a persistence backend, with the Store dispatch. They
are a separate protocol for the same JVM method-size limit as AutomationStore.
Subagent budget operations of a persistence backend, with the `Store` dispatch. They are a separate protocol for the same JVM method-size limit as `AutomationStore`.
(db-agent-extend-budget! db-info session-id iterations)Add iterations to one child budget within the schema maximum. Answer the new row or nil.
Add iterations to one child budget within the schema maximum. Answer the new row or nil.
(db-agent-resume! db-info session-id turns now)Queue one idle child for a follow-up task in one transaction, under the active cap. turns
is its turn count before the task. Answer the new row or nil.
Queue one idle child for a follow-up task in one transaction, under the active cap. `turns` is its turn count before the task. Answer the new row or nil.
Automation operations of a persistence backend, with the Store dispatch. They
are a separate protocol because one protocol with every op exceeds the JVM limit
for the size of one method. Rows keep column names. A definition is canonical
JSON with string keys.
Automation operations of a persistence backend, with the `Store` dispatch. They are a separate protocol because one protocol with every op exceeds the JVM limit for the size of one method. Rows keep column names. A definition is canonical JSON with string keys.
(db-automation-get db-info id)(db-automation-last-runs db-info)The newest run of each automation that has runs, by automation id.
The newest run of each automation that has runs, by automation id.
(db-automation-update-run! db-info id statuses attrs)Change a run only while its status is in statuses. Answer the new row or nil.
Change a run only while its status is in `statuses`. Answer the new row or nil.
(db-automation-update-delivery! db-info id attrs)(db-automation-put! db-info row)(db-automation-prune-runs! db-info automation-id limit)(db-automation-run db-info id)One run, with the name of its automation as automation_name.
One run, with the name of its automation as `automation_name`.
(db-automation-list db-info)(db-automation-runs db-info opts)Runs newest first, each with automation_name.
Runs newest first, each with `automation_name`.
(db-automation-delete! db-info id)(db-automation-enqueue-delivery! db-info row)(db-automation-stamps db-info)The id, enabled and updated_at of each automation, without the definition.
The `id`, `enabled` and `updated_at` of each automation, without the definition.
(db-automation-claim-run! db-info row)Insert a run unless its trigger key exists. Answer the inserted row or nil.
Insert a run unless its trigger key exists. Answer the inserted row or nil.
(db-automation-due-deliveries db-info now limit)Due pending callbacks, with the current callback_url and callback_secret.
Due pending callbacks, with the current `callback_url` and `callback_secret`.
(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-create-connection! db-spec)Open a persistence connection from db-spec.
Common spec forms: nil - no DB (returns nil) :memory - in-memory ephemeral store "path/to.db" - file-backed store {:backend :sqlite :path ...} - explicit backend selection {:backend :sqlite :datasource ds} - caller-owned DataSource
SQLite is the only backend; a spec naming another :backend is refused.
Open a persistence connection from `db-spec`.
Common spec forms:
nil - no DB (returns nil)
:memory - in-memory ephemeral store
"path/to.db" - file-backed store
{:backend :sqlite :path ...} - explicit backend selection
{:backend :sqlite :datasource ds} - caller-owned DataSource
SQLite is the only backend; a spec naming another `:backend` is refused.(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.
The backend owns backend-specific recognition; unknown errors fall
back to (ex-message e).
Translate a persistence exception into something a human can act on. The backend owns backend-specific recognition; unknown errors fall back to `(ex-message e)`.
(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.
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.
Queued-turn operations of a persistence backend, with the Store dispatch. They
are a separate protocol for the same JVM method-size limit as AutomationStore.
Queued-turn operations of a persistence backend, with the `Store` dispatch. They are a separate protocol for the same JVM method-size limit as `AutomationStore`.
(db-list-queued-turn-attachments db-info queued-turn-ids)(db-store-queued-turn-attachments! db-info
session-turn-soul-id
queued-turn-id
attachments)Every operation a persistence backend implements. The first argument is the
store db-create-connection! opened, or nil when there is none; every value
dispatches to the SQLite backend.
Every operation a persistence backend implements. The first argument is the store `db-create-connection!` opened, or nil when there is none; every value dispatches to the SQLite backend.
(db-list-session-turn-iterations db-info session-turn-ref)(db-get-session db-info ref)(db-workspace-touch-focus! db-info workspace-id)(db-archived-session-group-ids db-info)(db-latest-session-state-id db-info session-id)(db-list-session-groups db-info project-id opts)(db-seed-session-read-marks! db-info reader-id marks)(db-list-session-attachments db-info session-id)(db-append-iteration-attachment! db-info iteration-id att)(db-session-usage-stats db-info session-id)(db-search-session-matches db-info channel query)(db-search-session-matches db-info channel query session-ids)(db-checkpoint-session-turn-ctx! db-info session-turn-id state-id ctx)(db-activity-settle! db-info aid outcome summary)(db-adopt-and-reorder-project-sessions! db-info project-id session-ids)(db-list-sessions db-info channel)(db-list-session-turns-iterations-meta db-info session-turn-ids)(db-latest-turn-request-usage db-info session-turn-id)(db-agent-update! db-info session-id changes)(db-list-extension-aggregates db-info opts)(db-update-session-turn! db-info session-turn-id opts)Write a turn's terminal outcome. The facade bounds the DIAGNOSTIC text before
the backend sees it, so 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. The facade bounds the DIAGNOSTIC text before the backend sees it, so the write that records HOW a turn ended can never be lost to an unbounded error message (see [[max-persisted-error-chars]]).
(db-set-session-archived! db-info session-id archived?)(db-session-state-list-for-workspace db-info workspace-id)(db-fork-session-at-turn! db-info session-id opts)(db-reorder-project-sessions! db-info project-id session-ids)(db-create-extension-aggregate! db-info opts)(db-workspace-update-state! db-info workspace-id new-state)(db-council-unavailable! db-info sid id)(db-list-turn-all-attachments db-info session-turn-soul-id)(db-get-project-by-root db-info owner-id root)(db-routing-locked? db-info session-id)(db-list-turns-attachments db-info session-turn-soul-ids)(db-put-extension-aggregate! db-info opts)(db-list-iterations-attachments-meta db-info iteration-ids)(db-load-ctx-history db-info session-id)(db-get-session-group db-info group-id)(db-get-session-prompt-cache-state db-info session-state-id)(db-compare-session-goal! db-info session-id revision goal)(db-list-iteration-attachments-meta db-info iteration-id)(db-delete-session-group! db-info group-id)(db-store-iteration! db-info opts)Store one iteration row. The facade refuses opts that is not a map or lacks
:session-turn-id before the backend sees it.
Store one iteration row. The facade refuses `opts` that is not a map or lacks `:session-turn-id` before the backend sees it.
(db-session-state-set-workspace! db-info session-state-id workspace-id)(db-search db-info query opts)Backend-neutral full-text search. The backend 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. The backend 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-set-session-favorite! db-info session-id is-favorite)(db-list-session-turns-iterations db-info session-turn-ids)(db-store-session! db-info opts)(db-council-pending db-info sid activation gid after limit)(db-list-session-turns db-info session-ref)(db-agent-claim-iteration! db-info session-id)(db-improve-project-ids db-info)(db-find-session-by-external db-info channel ext-id)(db-list-session-states db-info session-id)(db-list-iterations db-info iteration-ids)(db-council-delivered! db-info sid ids)(db-workspace-list-drafts db-info)(db-list-projects db-info opts)(db-council-source db-info sid source)(db-mark-session-read! db-info reader-id session-id seen-answers)(db-get-extension-aggregate db-info opts)(db-council-machine-name db-info)(db-council-page db-info gid thread roots? after limit)(db-council-replay db-info sid key)(db-edit-scoped-settings! db-info scope target-id edit)(db-workspace-update-label! db-info workspace-id label)(db-lock-routing! db-info session-id locked?)(db-improve-list db-info opts)(db-council-set-machine-name! db-info name)(db-improve-update! db-info id attrs)(db-create-project! db-info opts)(db-improve-get db-info id)(db-improve-apply-review! db-info proposal still-current?)(db-resolve-session-id db-info sel)(db-update-project! db-info project-id opts)(db-set-scoped-setting! db-info scope target-id setting-id value)(db-workspace-insert! db-info opts)(db-agent-checkpoint db-info session-id)(db-create-session-group! db-info project-id opts)(db-council-unanswered db-info sid ids)(db-council-insert! db-info row recipients infer-reply?)(db-project-session-ids db-info project-id)(db-list-session-attachments-meta db-info session-id)(db-set-session-group! db-info session-id group-id)(db-agent-list db-info leader-id)(db-swap-extension-aggregate! db-info opts f args)(db-repo-focus-get db-info repo-id)(db-retry-session-turn! db-info session-turn-soul-id opts)(db-workspace-get db-info workspace-id)(db-update-session-group! db-info group-id opts)(db-get-session-goal db-info session-id)(db-fork-session! db-info session-id opts)(db-list-session-turns-by-status db-info status)(db-council-bind-wake! db-info entry-id sid activation)(db-scoped-settings db-info scope target-id)(db-claim-session! db-info ref)(db-session-subagent-usage db-info session-id)Summed usage of every subagent below one session, at any depth, in one query.
Summed usage of every subagent below one session, at any depth, in one query.
(db-read-attachment db-info attachment-id)(db-repo-focus-set! db-info repo-id workspace-id)(db-session-read-marks db-info reader-id)(db-improve-create! db-info attrs)(db-delete-session-tree! db-info id)(db-update-session-title! db-info ref title)(db-workspace-list-by-repo db-info repo-id)(db-workspace-list-by-repo db-info repo-id state-set)(db-workspace-for-session db-info session-state-id)(db-list-turn-attachments db-info session-turn-soul-id)(db-search-session-ids db-info channel query)(db-list-session-turn-states db-info session-turn-id)(db-list-session-turns-meta db-info session-ref)(db-get-project db-info project-id)(db-read-session-turn db-info session-ref turn-ref)(db-council-interrupt! db-info sid activation)(db-council-get db-info 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-list-iteration-attachments db-info iteration-id)(db-agent-info db-info session-id)(db-activity-page db-info sid aid opts)(db-set-session-prompt-cache-state! db-info session-state-id state)(db-load-latest-ctx db-info session-id)(db-list-iterations-attachments db-info iteration-ids)(db-activity-apply! db-info sid aid event)(db-set-session-model-pref! db-info session-id provider model)(db-delete-extension-aggregates! db-info opts)(db-session-group-session-ids db-info group-id)(db-set-turn-attachment-transcription! db-info
session-turn-soul-id
position
transcription
segments)(db-delete-project! db-info project-id)(db-store-session-turn! db-info opts)(db-get-session-model-pref db-info session-id)(db-log! db-info opts)(db-turn-history db-info session-ref)(db-set-session-project! db-info session-id project-id)(store-implementation)Expand, inside a backend namespace, to its op map for Store, AutomationStore,
QueueStore and AgentStore: every op keyed to the backend's own fn of the same name. A
backend missing an op fails to compile instead of failing at its first call.
Expand, inside a backend namespace, to its op map for `Store`, `AutomationStore`, `QueueStore` and `AgentStore`: every op keyed to the backend's own fn of the same name. A backend missing an op fails to compile instead of failing at its first call.
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 |