alkstore/tasks/sqlite-substrate-safety-comments.md

id, name, status, depends_on, scope, risk, impact, level, tags

id	name	status	depends_on	scope	risk	impact	level	tags
sqlite-substrate-safety-comments	SAFETY comments on the substrate UDF blocks, riding a PROVENANCE delta (review 004 item 15)	completed		narrow	low	isolated	implementation	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

• Each of the eight UDF blocks (plus any same-class neighbors included) carries a // SAFETY comment stating the concrete soundness invariant
• 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)
• No behavioral change: the substrate floor tests and the engine's tests green unchanged
• 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.