Documentation
¶
Overview ¶
Package manifest defines the migration safety manifest and its verifier — the HOST-3 contract (ADR-015). A manifest classifies whether a migration is destructive; the verifier proves that classification matches the executable SQL, so a deployment host (e.g. Gombit Cloud) can gate destructive migrations without blindly trusting a declared "safety" field (DESIGN.md §29–§31).
Gombit classifies and verifies. It does not implement the approval gate — a host owns the policy of blocking a data-loss migration pending confirmation (DESIGN.md §32). The manifest does not touch the framework_migrations table (build plan D4); its sql_sha256 is anti-tamper binding, not drift detection.
Index ¶
Constants ¶
const ManifestVersion = 1
ManifestVersion is the schema version of an emitted manifest. A host can fail loudly on an unknown version.
Variables ¶
var ( ErrHashMismatch = errors.New("manifest: sql hash mismatch") ErrClassificationMismatch = errors.New("manifest: classification mismatch") )
ErrHashMismatch and ErrClassificationMismatch let callers distinguish a tampered-SQL failure from a mis-declared-safety failure.
Functions ¶
func Verify ¶
func Verify(m SafetyManifest, sql string) error
Verify proves a manifest is consistent with the executable SQL. It fails when
- the manifest version is unknown;
- sql_sha256 does not match the SQL (the SQL was tampered with after review);
- the declared operations or requires_confirmation disagree with what the SQL actually does (e.g. a manifest claims non_destructive while the SQL drops a column).
A host consumes Verify's result; it never trusts the manifest's own fields (DESIGN.md §31).
Types ¶
type OpKind ¶
type OpKind string
OpKind is a classified migration operation. The set is closed; unrecognized statements classify as OpOther (HOST-3 / ADR-015).
const ( OpCreateTable OpKind = "create_table" OpAddColumn OpKind = "add_column" OpCreateIndex OpKind = "create_index" OpDropColumn OpKind = "drop_column" OpDropTable OpKind = "drop_table" OpDropIndex OpKind = "drop_index" OpRenameTable OpKind = "rename_table" OpRenameColumn OpKind = "rename_column" OpAlterColumn OpKind = "alter_column" OpOther OpKind = "other" )
type Operation ¶
type Operation struct {
Kind OpKind `json:"kind"`
Resource string `json:"resource,omitempty"`
Column string `json:"column,omitempty"`
Safety Safety `json:"safety"`
}
Operation is one classified statement from a migration.
func Classify ¶
Classify parses migration SQL into a closed set of operations. It is a statement-level DDL classifier (not a full SQL parser): it strips comments, splits on ';', and matches each statement's leading DDL. It handles the Postgres ("), MySQL (`) and SQLite quoting Atlas emits.
Its purpose is safety classification, so it is deliberately fail-safe: only recognized additive/metadata statements are non_destructive; anything it does not positively recognize as safe — including UPDATE, unrecognized DROPs, and statements it cannot parse — classifies as data_loss so a host reviews it.
type SafetyManifest ¶
type SafetyManifest struct {
ManifestVersion int `json:"manifest_version"`
Migration Migration `json:"migration"`
// SQLSHA256 binds the manifest to the exact reviewed SQL (anti-tamper).
SQLSHA256 string `json:"sql_sha256"`
// RequiresConfirmation is true when any operation loses data.
RequiresConfirmation bool `json:"requires_confirmation"`
Operations []Operation `json:"operations"`
}
SafetyManifest is the safety classification of one migration's SQL.
func Generate ¶
func Generate(mig Migration, sql string) SafetyManifest
Generate builds the canonical manifest for a migration's SQL: the operations classified from the SQL, whether confirmation is required, and the SQL hash.
Source Files