bookclerk_library::sql_plan
Host-owned generic SQL atomic plans for database adapters. Host-owned SQL atomic plans for database plugins.
The library compiles Bookclerk domain operations into a typed
bookclerk_plugin_abi::ExecuteRequest plus host-only
crate::sql_plan::host_ir::AtomicSelection indexes. Database guests
execute the statements as one transaction and return a typed
bookclerk_plugin_abi::ExecuteReply.
| Item | Kind | Summary |
|---|---|---|
PlanStmtResult |
struct | Rows produced by one plan statement. |
CompiledAtomic |
struct | Compiled typed request plus host result-selection indexes. |
execute_compiled_on |
function | Executes a compiled named atomic as one transaction and interprets the reply. |
execute_compiled_on_capped |
function | Like execute_compiled_on, failing when a statement returns more than max_result_rows. |
execute_typed_on |
function | Executes a typed request as one transaction on the opened adapter connection against the host library. |
execute_typed_on_binding |
function | Typed execute against an isolated plugin binding. |
execute_typed_on_session |
function | execute_typed_on with session cancel / deadline checks. |
event_inflight_slot |
function | Slot key that serializes in-flight event deliveries for one plugin class. |
lock_serialization_slot |
function | Inserts the slot row if missing, then bumps it (transaction-scoped write lock). |
run_typed_conn_vectors |
function | Runs the shared contract suite through the host stamp + adapter execute path. |
run_typed_contract_vectors |
function | Native typed contract suite (ExecuteRequest → ExecuteReply). |
run_typed_request_vectors |
function | Runs the shared contract suite through a typed ExecuteRequest callback. |
stamp_typed_vector |
function | Desugars and stamps proofs for one vector, recording DDL in catalog. |
validate_plan |
function | Rejects a compiled plan that exceeds negotiated guest limits or has out-of-range selectors. |
validate_execute_request |
function | Rejects a typed ExecuteRequest that exceeds negotiated guest limits. |
validate_proven_execute_request |
function | After host typecheck, reject a resolved batch whose proven lowered size exceeds negotiated maxLoweredStatementBytes. |
authorize_typed_request |
function | Host-authorizes a guest typed batch: overwrite statement kinds, enforce negotiated caps, and stamp the canonical Cap'n request hash. |
admit_typed_request |
function | Whether authorize_typed_request would accept req, without paying for its digest. |
execute_guest_atomic_with |
function | Authorizes, receipt-wraps, executes, and unwraps one guest typed batch. |
authorize_guest_typed_request |
function | Authorizes a guest-authored typed batch. |
wake_page_for_max_binds |
function | Wake page size from negotiated maxBinds (SET/EXISTS overhead is 4 binds). |
host_statement_kind |
function | Host-authored statement shape for the wire kind field. |
proxy_read_kind |
function | Kind for a SeaORM proxy read. SELECT/WITH/VALUES become Select (LIMIT-wrapped). RETURNING stays Returning. Everything else (PRAGMA, schema introspection) is Returning so it is not LIMIT-wrapped. |
unquote_sea_identifiers |
function | Drops SeaORM double-quoted identifiers so typed execute sees SQL v1 names. |
proxy_write_kind |
function | Kind for a SeaORM proxy write. RETURNING is preserved; other DML is Execute. |
proxy_insert_returning_identity |
function | Rewrites a SeaORM proxy single-row INSERT to return the table's identity key. |
JOB_QUEUE_SLOT |
constant | Slot key for job admit / claim / scratch-quota serialization. |
host_ir: Domain result-selection metadata kept beside a typedbookclerk_plugin_abi::ExecuteRequest.
pub struct PlanStmtResult {
pub rows: Vec<Value>,
pub rows_affected: u64,
}
Rows produced by one plan statement.
Fields
rows: Result-set rows (empty for DML).rows_affected: Engine-reported rows affected.
Implements: Clone, Debug, Default, From<&StatementResult>
pub struct CompiledAtomic {
pub request: ExecuteRequest,
pub selection: AtomicSelection,
pub expected_hash: String,
}
Compiled typed request plus host result-selection indexes.
Fields
request: Typed request executed by the guest. Its wirerequest_hashis empty;authorize_typed_requeststamps the canonical Cap'n digest.selection: Host indexes used to interpret the typed reply.expected_hash: Domain receipt hash (SHA-256 hex) bound into the receipt SQL and compared on receipt replay. Never sent as the wirerequest_hash.
pub fn into_typed_request(self, operation_id: impl Into<String>) -> ExecuteRequest
Typed ExecuteRequest for adapter execute (Cap'n data plane).
Implements: Clone, Debug
pub async fn execute_compiled_on(
db: &DatabaseConnection,
compiled: CompiledAtomic,
) -> Result<DbAtomicResult>
Executes a compiled named atomic as one transaction and interprets the reply.
Returns LibraryError::Orm when a statement fails. Application statuses
are returned as DbAtomicResult, not errors.
pub async fn execute_compiled_on_capped(
db: &DatabaseConnection,
compiled: CompiledAtomic,
max_result_rows: u32,
) -> Result<DbAtomicResult>
Like execute_compiled_on, failing when a statement returns more than max_result_rows.
max_result_rows of 0 means unlimited.
Returns LibraryError::Orm when a statement fails or exceeds the row cap.
pub async fn execute_typed_on(
db: &DatabaseConnection,
req: &ExecuteRequest,
max_result_rows: u32,
) -> Result<ExecuteReply>
Executes a typed request as one transaction on the opened adapter connection against the host library.
Merges crate::migrations::host_sql_type_env so host DML typechecks
against library tables. Isolated plugin bindings must use
execute_typed_on_binding.
Returns LibraryError::Orm when a statement fails.
pub async fn execute_typed_on_binding(
db: &DatabaseConnection,
req: &ExecuteRequest,
_timing_source: &str,
max_result_rows: u32,
catalog: &SqlTypeEnv,
) -> Result<ExecuteReply>
Typed execute against an isolated plugin binding.
catalog is the binding type environment (bootstrap plus already-applied
plugin schema). It must not be the host library catalog.
Returns LibraryError::Orm when a statement fails.
pub async fn execute_typed_on_session(
db: &DatabaseConnection,
req: &ExecuteRequest,
max_result_rows: u32,
session: AtomicSession,
) -> Result<ExecuteReply>
execute_typed_on with session cancel / deadline checks.
Always merges the host library type environment. Binding schema apply
must call execute_typed_on_binding instead.
Returns LibraryError::Orm when a statement fails or the session is interrupted.
pub fn event_inflight_slot(plugin_id: &str, resource_class: &str) -> String
Slot key that serializes in-flight event deliveries for one plugin class.
pub async fn lock_serialization_slot<C>(
db: &C,
in_process: bool,
slot_key: &str,
) -> Result<()>
where
C: ConnectionTrait + StreamTrait,
Inserts the slot row if missing, then bumps it (transaction-scoped write lock).
Canonical SQL uses ? placeholders. Host transport never lowers; adapters
realize INSERT OR IGNORE at the execute edge. This helper must run on the
caller's transaction, not a nested BEGIN. in_process of false is
canonical leftover SQL (production proxy). true physically lowers once
on the opened adapter connection.
Returns crate::LibraryError::Orm when either statement fails.
pub async fn run_typed_conn_vectors(db: &DatabaseConnection, connect: DbCapabilities)
Runs the shared contract suite through the host stamp + adapter execute path.
Panics when a vector fails.
pub async fn run_typed_contract_vectors<F, Fut>(
connect: DbCapabilities,
row_cap: u32,
run: F,
)
where
F: FnMut(ExecuteRequest, u32) -> Fut,
Fut: Future<Output = Result<ExecuteReply, String>>,
Native typed contract suite (ExecuteRequest → ExecuteReply).
Every reply is validated against its request before the vector's own assertions run.
pub async fn run_typed_request_vectors<F, Fut, E>(
connect: DbCapabilities,
advertised_cap: u32,
run: F,
)
where
F: FnMut(ExecuteRequest) -> Fut,
Fut: Future<Output = Result<ExecuteReply, E>>,
E: Display,
Runs the shared contract suite through a typed ExecuteRequest callback.
advertised_cap is the adapter's negotiated maxResultRows. The harness does
not wrap SQL or post-reject oversized results.
Panics when a vector fails.
pub fn stamp_typed_vector(
req: ExecuteRequest,
catalog: &mut SqlTypeEnv,
) -> Result<AdapterExecuteRequest, String>
Desugars and stamps proofs for one vector, recording DDL in catalog.
Adapter-boundary tests (guest execute) must stamp against the host catalog plus tables created by earlier vectors.
Returns when typecheck fails.
pub fn validate_plan(compiled: &CompiledAtomic, caps: &DbCapabilities) -> Result<()>
Rejects a compiled plan that exceeds negotiated guest limits or has out-of-range selectors.
Returns crate::LibraryError::Other when the plan cannot be sent.
pub fn validate_execute_request(req: &ExecuteRequest, caps: &DbCapabilities) -> Result<()>
Rejects a typed ExecuteRequest that exceeds negotiated guest limits.
maxRequestBytes is measured against the Cap'n-encoded ExecuteRequest.
Returns crate::LibraryError::LimitExceeded when a negotiated cap is
exceeded and crate::LibraryError::Other when the request cannot be
sent for another reason.
pub fn validate_proven_execute_request(
req: &ExecuteRequest,
proofs: &[ResolvedStatement],
caps: &DbCapabilities,
) -> Result<()>
After host typecheck, reject a resolved batch whose proven lowered size
exceeds negotiated maxLoweredStatementBytes.
Call this with the real bookclerk_plugin_abi::ResolvedStatement proofs
before adapter dispatch. validate_execute_request only has an empty
catalog, so INTEGER column arithmetic is charged here.
Returns crate::LibraryError::Other when proofs are missing/mismatched
and crate::LibraryError::LimitExceeded when the standardized lowering
upper bound exceeds the advertised ceiling.
pub fn authorize_typed_request(
req: &mut ExecuteRequest,
caps: &DbCapabilities,
) -> Result<()>
Host-authorizes a guest typed batch: overwrite statement kinds, enforce negotiated caps, and stamp the canonical Cap'n request hash.
A non-empty guest requestHash must match the host digest (retry token).
An empty operationId is replaced with a fresh UUID.
Returns crate::LibraryError::Other when the request exceeds caps, the
retry hash does not match, or the canonical digest cannot be encoded.
pub fn admit_typed_request(req: &mut ExecuteRequest, caps: &DbCapabilities) -> Result<()>
Whether authorize_typed_request would accept req, without paying
for its digest.
A host read probes each chunk of a lookup with this before sending it, and the proxy then authorizes the statement for real, so the probe's digest was thrown away. The probe stamps a placeholder of the digest's exact length instead, so the size limits see the same request bytes, and checks the TEXT the digest's encoding would have refused.
The errors of authorize_typed_request, except a retry-token
mismatch: req must carry no requestHash.
pub async fn execute_guest_atomic_with<F, Fut>(
req: ExecuteRequest,
caps: &DbCapabilities,
policy: &GuestSqlPolicy,
exec: F,
) -> Result<ExecuteReply, PluginError>
where
F: FnOnce(AdapterExecuteRequest) -> Fut,
Fut: Future<Output = Result<ExecuteReply, PluginError>>,
Authorizes, receipt-wraps, executes, and unwraps one guest typed batch.
The composable core of
LibraryStore::execute_guest_atomic
for callers that execute on something other than the library connection —
e.g. an isolated plugin database binding session. exec receives the
receipt-wrapped envelope and must run it atomically on the target
database (which needs its own bookclerk_receipts table — see
crate::migrations::binding_bootstrap_ops).
Returns bookclerk_plugin_abi::PluginError::invalid_params when the SQL
is outside the guest grammar or policy,
bookclerk_plugin_abi::PluginError::limit_exceeded when the request or
its result exceeds a negotiated cap, and the executor's error or a
validation error when the batch fails.
pub fn authorize_guest_typed_request(
req: &mut ExecuteRequest,
caps: &DbCapabilities,
policy: &GuestSqlPolicy,
) -> Result<()>
Authorizes a guest-authored typed batch.
Pipeline: plugin SQL → SQL-v1 grammar validation → binding
scope/security authorization → capability/limit validation → canonical
bookclerk_plugin_abi::ExecuteRequest. Adapter-edge lowering happens
later, at execute, against the isolated physical DB.
Host schema DDL must use authorize_typed_request directly.
Returns crate::LibraryError::Other when the SQL is outside the guest
grammar or fails host validation.
pub fn wake_page_for_max_binds(max_binds: u32) -> u64
Wake page size from negotiated maxBinds (SET/EXISTS overhead is 4 binds).
pub fn host_statement_kind(sql: &str) -> DbPlanStatementKind
Host-authored statement shape for the wire kind field.
Adapters must not reparse SQL; they trust this classification.
pub fn proxy_read_kind(sql: &str) -> DbPlanStatementKind
Kind for a SeaORM proxy read. SELECT/WITH/VALUES become Select
(LIMIT-wrapped). RETURNING stays Returning. Everything else (PRAGMA,
schema introspection) is Returning so it is not LIMIT-wrapped.
pub fn unquote_sea_identifiers(sql: &str) -> String
Drops SeaORM double-quoted identifiers so typed execute sees SQL v1 names.
String literals, including doubled single quotes, are preserved.
pub fn proxy_write_kind(sql: &str) -> DbPlanStatementKind
Kind for a SeaORM proxy write. RETURNING is preserved; other DML is
Execute.
pub fn proxy_insert_returning_identity(sql: &str, catalog: &SqlTypeEnv) -> Option<String>
Rewrites a SeaORM proxy single-row INSERT to return the table's identity
key.
The typed DB ABI carries no last-insert-id (D1 / Postgres portability), so
a proxy write cannot report SeaORM's last_insert_id from rowsAffected.
When sql is an INSERT [OR …] INTO t (…) VALUES (…) of exactly one tuple
and catalog gives t an INTEGER PRIMARY KEY AUTOINCREMENT column, this
returns sql with RETURNING <identity> appended. The result is proven
single-row (bookclerk_plugin_abi::returning_single_row_proven), so it
may carry maxRows = 1 on every adapter, including D1.
Returns None for every other shape (already RETURNING, INSERT … SELECT, multi-tuple VALUES, ON CONFLICT upserts, tables without an
identity column); those keep the plain execute shape.
pub const JOB_QUEUE_SLOT: &str = "job-queue";
Slot key for job admit / claim / scratch-quota serialization.
Generated from crates/bookclerk-library at main · View as Markdown