bookclerk_db_exec::guest_receipt

Development These docs follow the development version and change with every merge.

Last updated View as Markdown

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.

Functions

guest_batch_is_read_only

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.

is_guest_receipt_result_lost

pub fn is_guest_receipt_result_lost(err: &DbErr) -> bool

True when err is GUEST_RECEIPT_RESULT_LOST.

is_guest_receipt_stub_insert

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.

strip_guest_receipt_write_gate

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.

guest_receipt_applied_stmt

pub fn guest_receipt_applied_stmt(operation_id: &str) -> TypedDbStatement

Host UPDATE that marks a claimed stub as applied after ungated guest SQL.

prior_receipt_exists

pub fn prior_receipt_exists(stmt: &StatementResult) -> bool

True when the prior-receipt SELECT returned a row.

prior_receipt_is_claimed

pub fn prior_receipt_is_claimed(stmt: &StatementResult) -> bool

True when stmt is an in-flight GUEST_RECEIPT_STATUS_CLAIMED receipt.

receipt_hash_from

pub fn receipt_hash_from(stmt: &StatementResult) -> Option<String>

Reads request_hash from a prior-receipt select result, if any row exists.

prior_receipt_should_resume_guest

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).

prior_receipt_is_read_only_replay

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.

should_skip_remaining_guest_work

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).

pad_skipped_guest_results

pub fn pad_skipped_guest_results(results: &mut Vec<StatementResult>, total: usize)

Pads skipped guest + stub results so the wrap shape stays intact.

guest_receipt_finalize_stmts

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.

Errors

Returns DbErr when the envelope is malformed or the payload exceeds GUEST_TYPED_REPLAY_PAYLOAD_MAX_BYTES.

guest_receipt_read_only_finalize_stmt

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.

Constants

GUEST_TYPED_REPLAY_PAYLOAD_MAX_BYTES

pub const GUEST_TYPED_REPLAY_PAYLOAD_MAX_BYTES: usize = 65536;

Maximum UTF-8 bytes stored in bookclerk_receipts.payload for guest replay.

GUEST_READ_ONLY_REPLAY_PAYLOAD

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.

GUEST_RECEIPT_RESULT_LOST

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.

GUEST_RECEIPT_STATUS_CLAIMED

pub const GUEST_RECEIPT_STATUS_CLAIMED: &str = "claimed";

In-flight guest-receipt claim (D1 commits the stub INSERT before DDL).

GUEST_RECEIPT_STATUS_OK

pub const GUEST_RECEIPT_STATUS_OK: &str = "ok";

Finalized guest-receipt row; payload is the durable replay body.

GUEST_RECEIPT_STATUS_APPLIED

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).

GUEST_RECEIPT_WRITE_GATE

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.

GUEST_RECEIPT_WRAP_PREFIX

pub const GUEST_RECEIPT_WRAP_PREFIX: usize = 2;

Prune + prior-select prefix ahead of the guest statements.

GUEST_RECEIPT_STUB_SUFFIX

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