---
id: sqlite-substrate-safety-comments
name: SAFETY comments on the substrate UDF blocks, riding a PROVENANCE delta (review 004 item 15)
status: completed
depends_on: []
scope: narrow
risk: low
impact: isolated
level: implementation
tags: [review-004-fixes, sqlite-engine, substrate, provenance]
---

## Description

The eight `unsafe { ctx.get_connection() }` UDF blocks
(`alkstore-sqlite/src/substrate/ops.rs:147-236`) carry no `// SAFETY`
justification comments, per
`docs/reviews/004-pre-release-general-review.md` §"Findings recorded,
not fixed" item 15. The pattern is the standard rusqlite UDF shape and
provably constrained, but AGENTS.md's own carve-out ("inline comments
when a non-obvious safety constraint would otherwise be missed") says
this is where they'd live.

**The constraint that shapes this task**: the substrate is
lineage-port code under ADR-012 §3's diff-fidelity posture — comments
must ride a PROVENANCE delta. This task *is* the deliberate delta
vehicle: add the comments and register the delta; do not treat this as
a casual edit.

Each comment must state the *concrete* invariant that makes the access
sound (derive it from the rusqlite UDF contract and the substrate's
actual registration/usage — e.g. the connection the ctx hands out is
confined to the registered UDF call path on the single connection
thread), not a generic "this is safe" hand-wave.

While there: the review scoped to the eight blocks at ops.rs:147-236,
but the same `unsafe { ctx.get_connection() }` shape also appears at
`schema.rs:104` and `ops.rs:742` — check whether they are the same
class; if so, include them in the same delta (and say so in Notes);
if not, leave them and record why.

## Acceptance Criteria

- [x] Each of the eight UDF blocks (plus any same-class neighbors
      included) carries a `// SAFETY` comment stating the concrete
      soundness invariant
- [x] `src/substrate/PROVENANCE.md` carries a dated delta entry
      registering the comment-only change (diff-fidelity posture
      honored; the entry classifies the delta per the register's
      conventions)
- [x] No behavioral change: the substrate floor tests and the engine's
      tests green unchanged
- [x] `cargo test -p alkstore-sqlite`, clippy `-D warnings`, fmt
      clean; workspace gates green server-less

## References

- docs/reviews/004-pre-release-general-review.md §"Findings recorded,
  not fixed" item 15 (the finding, the PROVENANCE-delta requirement)
- docs/architecture/decisions/012-forked-substrate-design.md §3 (the
  diff-fidelity posture)
- alkstore-sqlite/src/substrate/PROVENANCE.md (the delta register)
- alkstore-sqlite/src/substrate/ops.rs:147-236 (the eight blocks)

## Notes

- Same-class neighbors **included**: `schema.rs:104` (the `notify`
  registration in `attach_notify`) and `ops.rs`'s test-module scalar
  probe (`a_panicking_savepoint_body_leaves_no_frame_on_the_scalar_path`)
  are the identical rusqlite UDF shape — registered on one connection,
  invoked only synchronously inside that connection's statement
  evaluation — so both joined the delta; all **ten** sites carry the
  comment.
- The comment states the concrete invariant, derived from rusqlite
  0.40's `Context::get_connection` contract (functions.rs; the issue
  #643 analysis behind its unsafety): the rebuilt `ConnectionRef`
  could alias a cross-thread access or outlive the callback — neither
  reachable here (each connection one-thread-at-a-time: rusqlite
  `Connection` is !Sync, the reader pool transfers owned connections,
  the writer lease is exclusive; the closure consumes the deref'd
  reference only within the callback's lifetime).
- Delta registered as **D-40** in `PROVENANCE.md`, category `hygiene`
  (comment-only, zero behavior change) — the deliberate exception to
  D-15's comment elision, riding a delta per ADR-012 §3.

## Summary

Added uniform `// SAFETY` comments at all ten `unsafe {
ctx.get_connection() }` UDF sites (the eight review-scoped blocks in
`attach_alkstore_functions`, plus the same-class `notify` registration
and the test-module savepoint-panic probe) and registered the
comment-only change as PROVENANCE delta D-40. Verified: `cargo test`
workspace green (alkstore-sqlite 203 passed, all crates green
unchanged), `cargo clippy --all-targets -- -D warnings` clean,
`cargo fmt --check` clean, `cargo build` green, fuzz gate
(`fuzz/shared`) green — comment-only diff, no behavior change.