sqlfold

Documentation

Overview

Package sqlfold is the SQL const-accumulation fold (docs/design/ sql-constfold-reclaim-plan.md): a sound, opt-in LABEL reclaimer that recovers the verb (and, when constant, the table) of a SQL statement assembled at runtime from compile-time-constant fragments — the dominant shape of the B2 "opaque SQL" frontier (a constant statement laundered through a strings.Builder), not genuinely dynamic SQL.

Soundness is asymmetric (plan §3, L1), and the asymmetry is the whole design:

• WRITE promotion needs only the constant LEADING verb. A statement whose constant prefix proves a mutating verb (INSERT/UPDATE/DELETE/…) is a write no matter what its variable tail appends — appending cannot un-write a write — so the recovered verb can only ADD to the write surface, never hide a write. The table is named only when it too is in the constant prefix.
• READ classification needs the WHOLE statement to be a single compile-time constant (every fragment constant, every placeholder a bound `$N`/`?`, no conditional or variable-cardinality fragment). Only then is there no unconstrained text splice through which a second, mutating statement could be smuggled (`"SELECT 1; " + var`). A read claim further requires a RECOGNIZED read verb (SELECT), so a data-modifying CTE (WITH … RETURNING), whose leading token canon/sql does not recognize, fails closed.

Anything the fold cannot prove to either standard returns ok=false: the caller leaves the effect exactly as opaque as it is today. The fold can only ever match or improve on the current label — never weaken a verdict.

Index

• Constants
• func ConstStringSet(v ssa.Value) ([]string, bool)
• func Recover(q ssa.Value) (op string, tables []string, ok bool)

Constants

const Via = "sql-constfold"

Via is the provenance tag carried on a boundary edge whose verb the fold recovered (plan §3, L3). It names the const-accumulation fold so a verdict that leaned on a reclaimed verb is auditable and a reviewer can diff folded vs base.

Functions

func ConstStringSet

func ConstStringSet(v ssa.Value) ([]string, bool)

ConstStringSet resolves v to the complete, finite set of compile-time string constants it can hold, or ok=false when it cannot PROVE completeness. It is the general const-string-set resolver the SQL table fold is built on (resolveConstSet), exposed so other sound label reclaimers reuse the SAME completeness discipline rather than re-deriving it — the bus reclaim-topic fold names a publish/consume target this way. The recovered set is verdict-neutral for its callers (a table or topic NAME), so over-listing can only refine a name or a diff, never move a pole.

func Recover

func Recover(q ssa.Value) (op string, tables []string, ok bool)

Recover returns the SQL operation and the table(s) the fold can soundly read off the query value q, plus whether it recovered anything. q is the string argument the labeler could NOT fold at the call site (a non-constant value); Recover traces it back through string concatenation and a fluent strings.Builder accumulator to the constant fragments behind it.

It emits a verb under exactly two disciplines (see the package doc): a mutating verb proven by the constant leading prefix (a write, tail irrelevant), or a SELECT proven by a wholly-constant statement (a read). Everything else abstains.

tables holds zero, one, or several table names. Empty means the verb is known but the table is dynamic (a fold-promoted write to an unnamed target). More than one means the table is a finite, provably-complete set of constants (phase 2): each is a real possible write target, so the caller emits one edge per table — an over-approximation in the safe direction (it can only over-list targets, never hide a write). Table naming is verdict-NEUTRAL: read/write keys on op, not the table, so a naming miss never changes a verdict.