# 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`](#guest_receipt_finalize_stmts) in the same atomic transaction before COMMIT.

| Item | Kind | Summary |
| --- | --- | --- |
| [`guest_batch_is_read_only`](#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`](#is_guest_receipt_result_lost) | function | True when `err` is `GUEST_RECEIPT_RESULT_LOST`. |
| [`is_guest_receipt_stub_insert`](#is_guest_receipt_stub_insert) | function | True when `sql` is the guest-receipt claim stub (`INSERT … WHERE NOT EXISTS`). |
| [`strip_guest_receipt_write_gate`](#strip_guest_receipt_write_gate) | function | Removes the **host-appended** `GUEST_RECEIPT_WRITE_GATE` predicate. |
| [`guest_receipt_applied_stmt`](#guest_receipt_applied_stmt) | function | Host UPDATE that marks a claimed stub as applied after ungated guest SQL. |
| [`prior_receipt_exists`](#prior_receipt_exists) | function | True when the prior-receipt SELECT returned a row. |
| [`prior_receipt_is_claimed`](#prior_receipt_is_claimed) | function | True when `stmt` is an in-flight `GUEST_RECEIPT_STATUS_CLAIMED` receipt. |
| [`receipt_hash_from`](#receipt_hash_from) | function | Reads `request_hash` from a prior-receipt select result, if any row exists. |
| [`prior_receipt_should_resume_guest`](#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`](#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`](#should_skip_remaining_guest_work) | function | True when wrap prefix results show a completed prior receipt (skip guest SQL). |
| [`pad_skipped_guest_results`](#pad_skipped_guest_results) | function | Pads skipped guest + stub results so the wrap shape stays intact. |
| [`guest_receipt_finalize_stmts`](#guest_receipt_finalize_stmts) | function | Builds finalize statements to persist a guest reply before COMMIT. |
| [`guest_receipt_read_only_finalize_stmt`](#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`](#guest_typed_replay_payload_max_bytes) | constant | Maximum UTF-8 bytes stored in `bookclerk_receipts.payload` for guest replay. |
| [`GUEST_READ_ONLY_REPLAY_PAYLOAD`](#guest_read_only_replay_payload) | constant | Payload stored for a read-only guest batch instead of its results. |
| [`GUEST_RECEIPT_RESULT_LOST`](#guest_receipt_result_lost) | constant | Error text when a receipt committed but the caller-visible payload was lost. |
| [`GUEST_RECEIPT_STATUS_CLAIMED`](#guest_receipt_status_claimed) | constant | In-flight guest-receipt claim (D1 commits the stub INSERT before DDL). |
| [`GUEST_RECEIPT_STATUS_OK`](#guest_receipt_status_ok) | constant | Finalized guest-receipt row; payload is the durable replay body. |
| [`GUEST_RECEIPT_STATUS_APPLIED`](#guest_receipt_status_applied) | constant | Claimed-owner guest SQL finished on D1 (prune + ungated guest in one HTTP). |
| [`GUEST_RECEIPT_WRITE_GATE`](#guest_receipt_write_gate) | constant | Write-predicate spliced onto guest DML by the host receipt wrap. |
| [`GUEST_RECEIPT_WRAP_PREFIX`](#guest_receipt_wrap_prefix) | constant | Prune + prior-select prefix ahead of the guest statements. |
| [`GUEST_RECEIPT_STUB_SUFFIX`](#guest_receipt_stub_suffix) | constant | Same-batch receipt stub INSERT after gated guest statements. |

## Functions

### guest_batch_is_read_only

```rust
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`](#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

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

True when `err` is [`GUEST_RECEIPT_RESULT_LOST`](#guest_receipt_result_lost).

### is_guest_receipt_stub_insert

```rust
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

```rust
pub fn strip_guest_receipt_write_gate(sql: &str) -> String
```

Removes the **host-appended** [`GUEST_RECEIPT_WRITE_GATE`](#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

```rust
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

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

True when the prior-receipt SELECT returned a row.

### prior_receipt_is_claimed

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

True when `stmt` is an in-flight [`GUEST_RECEIPT_STATUS_CLAIMED`](#guest_receipt_status_claimed) receipt.

### receipt_hash_from

```rust
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

```rust
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

```rust
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`](#guest_read_only_replay_payload)), whose reads run again on replay.

### should_skip_remaining_guest_work

```rust
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`](#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

```rust
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

```rust
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`](#guest_batch_is_read_only)) the
receipt stores [`GUEST_READ_ONLY_REPLAY_PAYLOAD`](#guest_read_only_replay_payload) instead of the rows, so
a large read is not bounded by the payload cap.

#### Errors

Returns [`DbErr`](https://docs.rs/sea_orm/latest/sea_orm/error/enum.DbErr.html) when the envelope is malformed or the payload exceeds
[`GUEST_TYPED_REPLAY_PAYLOAD_MAX_BYTES`](#guest_typed_replay_payload_max_bytes).

### guest_receipt_read_only_finalize_stmt

```rust
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`](#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

```rust
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

```rust
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 `SELECT`s 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`](#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

```rust
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

```rust
pub const GUEST_RECEIPT_STATUS_CLAIMED: &str = "claimed";
```

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

### GUEST_RECEIPT_STATUS_OK

```rust
pub const GUEST_RECEIPT_STATUS_OK: &str = "ok";
```

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

### GUEST_RECEIPT_STATUS_APPLIED

```rust
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`](#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

```rust
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

```rust
pub const GUEST_RECEIPT_WRAP_PREFIX: usize = 2;
```

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

### GUEST_RECEIPT_STUB_SUFFIX

```rust
pub const GUEST_RECEIPT_STUB_SUFFIX: usize = 1;
```

Same-batch receipt stub INSERT after gated guest statements.
