bookclerk_db_exec::guest_receipt
Guest-typed durable receipt finalize (same-transaction payload capture).
Host wrap lives in bookclerk-library; adapters run
guest_receipt_finalize_stmts in the same atomic transaction before COMMIT.
| Item | Kind | Summary |
|---|---|---|
guest_batch_is_read_only |
function | True when every guest statement inside the receipt wrap of req is a read-only SELECT. |
is_guest_receipt_result_lost |
function | True when err is GUEST_RECEIPT_RESULT_LOST. |
is_guest_receipt_stub_insert |
function | True when sql is the guest-receipt claim stub (INSERT … WHERE NOT EXISTS). |
strip_guest_receipt_write_gate |
function | Removes the host-appended GUEST_RECEIPT_WRITE_GATE predicate. |
guest_receipt_applied_stmt |
function | Host UPDATE that marks a claimed stub as applied after ungated guest SQL. |
prior_receipt_exists |
function | True when the prior-receipt SELECT returned a row. |
prior_receipt_is_claimed |
function | True when stmt is an in-flight GUEST_RECEIPT_STATUS_CLAIMED receipt. |
receipt_hash_from |
function | Reads request_hash from a prior-receipt select result, if any row exists. |
prior_receipt_should_resume_guest |
function | True when a claimed prior receipt belongs to guest_hash (resume ungated DDL). |
prior_receipt_is_read_only_replay |
function | True when a prior receipt for guest_hash recorded a read-only batch (GUEST_READ_ONLY_REPLAY_PAYLOAD), whose reads run again on replay. |
should_skip_remaining_guest_work |
function | True when wrap prefix results show a completed prior receipt (skip guest SQL). |
pad_skipped_guest_results |
function | Pads skipped guest + stub results so the wrap shape stays intact. |
guest_receipt_finalize_stmts |
function | Builds finalize statements to persist a guest reply before COMMIT. |
guest_receipt_read_only_finalize_stmt |
function | Host UPDATE that finalizes this batch's own stub as a read-only receipt when the batch failed after its stub committed. |
GUEST_TYPED_REPLAY_PAYLOAD_MAX_BYTES |
constant | Maximum UTF-8 bytes stored in bookclerk_receipts.payload for guest replay. |
GUEST_READ_ONLY_REPLAY_PAYLOAD |
constant | Payload stored for a read-only guest batch instead of its results. |
GUEST_RECEIPT_RESULT_LOST |
constant | Error text when a receipt committed but the caller-visible payload was lost. |
GUEST_RECEIPT_STATUS_CLAIMED |
constant | In-flight guest-receipt claim (D1 commits the stub INSERT before DDL). |
GUEST_RECEIPT_STATUS_OK |
constant | Finalized guest-receipt row; payload is the durable replay body. |
GUEST_RECEIPT_STATUS_APPLIED |
constant | Claimed-owner guest SQL finished on D1 (prune + ungated guest in one HTTP). |
GUEST_RECEIPT_WRITE_GATE |
constant | Write-predicate spliced onto guest DML by the host receipt wrap. |
GUEST_RECEIPT_WRAP_PREFIX |
constant | Prune + prior-select prefix ahead of the guest statements. |
GUEST_RECEIPT_STUB_SUFFIX |
constant | Same-batch receipt stub INSERT after gated guest statements. |
pub fn guest_batch_is_read_only(req: &ExecuteRequest, guest_len: usize) -> bool
True when every guest statement inside the receipt wrap of req is a
read-only SELECT.
guest_len is the wrap hint's guest statement count; the guest slice
starts after GUEST_RECEIPT_WRAP_PREFIX. An empty or malformed slice
is not read-only, so a write batch never skips its replay payload.
pub fn is_guest_receipt_result_lost(err: &DbErr) -> bool
True when err is GUEST_RECEIPT_RESULT_LOST.
pub fn is_guest_receipt_stub_insert(sql: &str) -> bool
True when sql is the guest-receipt claim stub (INSERT … WHERE NOT EXISTS).
D1 commits each HTTP batch immediately, so the adapter sends this statement
first and only runs ungated guest DDL after rows_affected = 1.
pub fn strip_guest_receipt_write_gate(sql: &str) -> String
Removes the host-appended GUEST_RECEIPT_WRITE_GATE predicate.
The wrap splices the gate into a code span (before RETURNING). A plugin
string or comment may contain the same text; only the last code-span match
is removed. Returns sql unchanged when that gate is absent. The caller
must drop the trailing operation_id bind the wrap appended for the gate.
pub fn guest_receipt_applied_stmt(operation_id: &str) -> TypedDbStatement
Host UPDATE that marks a claimed stub as applied after ungated guest SQL.
pub fn prior_receipt_exists(stmt: &StatementResult) -> bool
True when the prior-receipt SELECT returned a row.
pub fn prior_receipt_is_claimed(stmt: &StatementResult) -> bool
True when stmt is an in-flight GUEST_RECEIPT_STATUS_CLAIMED receipt.
pub fn receipt_hash_from(stmt: &StatementResult) -> Option<String>
Reads request_hash from a prior-receipt select result, if any row exists.
pub fn prior_receipt_should_resume_guest(stmt: &StatementResult, guest_hash: &str) -> bool
True when a claimed prior receipt belongs to guest_hash (resume ungated DDL).
pub fn prior_receipt_is_read_only_replay(stmt: &StatementResult, guest_hash: &str) -> bool
True when a prior receipt for guest_hash recorded a read-only batch
(GUEST_READ_ONLY_REPLAY_PAYLOAD), whose reads run again on replay.
pub fn should_skip_remaining_guest_work(
results: &[StatementResult],
total: usize,
guest_hash: &str,
) -> bool
True when wrap prefix results show a completed prior receipt (skip guest SQL).
An in-flight GUEST_RECEIPT_STATUS_CLAIMED row with the same hash must
not skip remaining work: D1 commits the stub INSERT before ungated
DDL, so a crash between those HTTP batches has to re-run idempotent DDL
and then finalize. A read-only receipt with the same hash does not skip
either: it stored no rows, so the reads run again and this attempt's
results are the reply. A prior row with a different hash still skips
(unwrap reports conflict).
pub fn pad_skipped_guest_results(results: &mut Vec<StatementResult>, total: usize)
Pads skipped guest + stub results so the wrap shape stays intact.
pub fn guest_receipt_finalize_stmts(
partial: &ExecuteReply,
guest_len: usize,
guest_hash: &str,
guest_read_only: bool,
) -> Result<Vec<TypedDbStatement>, DbErr>
Builds finalize statements to persist a guest reply before COMMIT.
Returns an empty list when the prior receipt row already carries payload.
When guest_read_only is true (see guest_batch_is_read_only) the
receipt stores GUEST_READ_ONLY_REPLAY_PAYLOAD instead of the rows, so
a large read is not bounded by the payload cap.
Returns DbErr when the envelope is malformed or the payload exceeds
GUEST_TYPED_REPLAY_PAYLOAD_MAX_BYTES.
pub fn guest_receipt_read_only_finalize_stmt(
operation_id: &str,
guest_hash: &str,
) -> TypedDbStatement
Host UPDATE that finalizes this batch's own stub as a read-only receipt when the batch failed after its stub committed.
For an adapter whose stub commits before it sees the result (D1), a
read-only guest batch that fails a result cap has committed only the
host's bookkeeping. Finalizing the stub with
GUEST_READ_ONLY_REPLAY_PAYLOAD leaves the receipt as a successful
read would have: a retry under the same operation id runs the reads
again and fails the same cap, instead of finding an unfinished claim.
Only a claimed row with this request's hash is touched, so another
request's receipt under the same id is left alone.
pub const GUEST_TYPED_REPLAY_PAYLOAD_MAX_BYTES: usize = 65536;
Maximum UTF-8 bytes stored in bookclerk_receipts.payload for guest replay.
pub const GUEST_READ_ONLY_REPLAY_PAYLOAD: &str = "{\"readOnly\":true}";
Payload stored for a read-only guest batch instead of its results.
A batch of SELECTs re-runs on replay (nothing is gated), so its rows
are not persisted and its result size is bounded by the result budget
the batch was read under, not by GUEST_TYPED_REPLAY_PAYLOAD_MAX_BYTES.
The host sees this marker on a prior receipt and returns the attempt's
own rows.
pub const GUEST_RECEIPT_RESULT_LOST: &str = "guest receipt committed without payload; original response lost";
Error text when a receipt committed but the caller-visible payload was lost.
pub const GUEST_RECEIPT_STATUS_CLAIMED: &str = "claimed";
In-flight guest-receipt claim (D1 commits the stub INSERT before DDL).
pub const GUEST_RECEIPT_STATUS_OK: &str = "ok";
Finalized guest-receipt row; payload is the durable replay body.
pub const GUEST_RECEIPT_STATUS_APPLIED: &str = "applied";
Claimed-owner guest SQL finished on D1 (prune + ungated guest in one HTTP).
Resume remaining guest work only for GUEST_RECEIPT_STATUS_CLAIMED. An
applied row means DML already ran; skip guest SQL and finalize (or
surface result-lost when payload is still empty).
pub const GUEST_RECEIPT_WRITE_GATE: &str = "NOT EXISTS (SELECT 1 FROM bookclerk_receipts WHERE operation_id = ?)";
Write-predicate spliced onto guest DML by the host receipt wrap.
D1 claimed-owner batches strip this after the stub INSERT commits, because the claim row would otherwise make the predicate false on first execution.
pub const GUEST_RECEIPT_WRAP_PREFIX: usize = 2;
Prune + prior-select prefix ahead of the guest statements.
pub const GUEST_RECEIPT_STUB_SUFFIX: usize = 1;
Same-batch receipt stub INSERT after gated guest statements.
Generated from crates/bookclerk-db-exec at main · View as Markdown