96 lines
4.3 KiB
Markdown
96 lines
4.3 KiB
Markdown
---
|
|
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. |