scaffold

type ConfigBlockLeaf struct {
	Type        string // proto scalar type, e.g. "string"
	Name        string // proto field name, e.g. "base_url"
	EnvVar      string // (forge.v1.config).env_var
	Description string // (forge.v1.config).description
}

type ConfigBlockResult struct {
	// File is the .proto file that declares the root config (and, when it
	// was added, the block).
	File string
	// AddedMessage / AddedField report the two halves this call wrote.
	// Both false is the idempotent no-op: the block was already declared
	// and composed.
	AddedMessage bool
	AddedField   bool
	// FieldNumber is the root config field number the block was given when
	// AddedField; zero otherwise.
	FieldNumber int
}

type ConfigBlockSpec struct {
	// Message is the block's message name, e.g. "AlpacaConfig".
	Message string
	// Field is the root config field holding it, e.g. "alpaca" (its Go
	// getter is GetAlpaca).
	Field string
	// Doc is the comment written above the message, one line per element.
	Doc []string
	// FieldDoc is the one-line comment written above the root field.
	FieldDoc string
	// Leaves are the block's fields, in declaration order.
	Leaves []ConfigBlockLeaf
}

type EntityFromProtoMigration struct {
	UpSQL string
	Notes []string
	// PendingRefColumns are this table's `<x>_id` columns that resolve to a
	// known entity whose table does not exist YET, so no constraint could be
	// emitted here. The caller carries them forward as this table's
	// ExistingTable.UnconstrainedRefColumns, and the referenced table's own
	// birth migration back-fills them.
	PendingRefColumns []string
	// BackfilledRefColumns names, per earlier table, the reference columns
	// THIS migration constrained on its behalf. The caller strikes them off
	// that table's pending list so a third birth cannot propose the same
	// constraint twice.
	BackfilledRefColumns map[string][]string
}

type EntityFromProtoSpec struct {
	// Table is the target table name (already pluralized/overridden).
	Table string
	// MessageFQ is the fully-qualified proto message the entity is born
	// from (recorded in the migration header for provenance).
	MessageFQ string
	// ProtoPkg is the service's own proto package — the boundary for
	// cross-package detection.
	ProtoPkg string
	// Fields is the message's descriptor schema, in declaration order.
	Fields []codegen.SchemaFieldDef
	// Enums maps fully-qualified enum names to their value names (the
	// CHECK-constraint vocabulary).
	Enums map[string][]string
	// SoftDelete adds the deleted_at column (set by the flag, the
	// `// forge:soft-delete` marker, or the message itself carrying a
	// deleted_at field).
	SoftDelete bool
	// Timestamps adds the managed created_at/updated_at columns.
	Timestamps bool
	// AppendOnly adds a DB guard (a trigger raising an exception) that
	// rejects every UPDATE/DELETE on the table — the storage half of the
	// `// forge:append-only` marker (the wire half omits Update/Delete
	// RPCs). An audit/ledger table: rows are immutable once written.
	AppendOnly bool
	// KnownTables is the set of table names an `<x>_id` FK may reference:
	// the applied schema UNION every table born in this run (descriptor
	// CRUD entities + `// forge:entity` messages). A `<x>_id` column whose
	// stem names no table in this set is polymorphic/auth
	// (user_id/actor_user_id/entity_id in a project with no such entity)
	// and gets NO foreign key — a REFERENCES to a table that doesn't exist
	// is worse than silence. Empty/nil suppresses every foreign key.
	KnownTables map[string]bool
	// ExistingTables are the tables that ALREADY EXIST at the moment this
	// migration runs — the applied schema plus everything born earlier in
	// the same sweep. It is what makes the emitted constraints applyable:
	// a REFERENCES may only name a table an EARLIER migration created.
	//
	// It also carries the reverse direction. A child born before its parent
	// could not constrain its own column; the parent's birth migration
	// back-fills that constraint, because the parent's migration is the
	// first point at which it can be applied. Between the two directions
	// every resolvable reference becomes a real constraint exactly once, in
	// whatever order the entities are born.
	//
	// Empty/nil means "nothing exists yet", which suppresses forward
	// constraints — the drift renderer runs this way.
	ExistingTables []ExistingTable
}

type ExistingTable struct {
	// Name is the table name.
	Name string
	// UnconstrainedRefColumns are its TEXT `<x>_id` columns that carry no
	// FOREIGN KEY yet — the columns a later table's birth may still be
	// able to constrain, once it creates the table they point at.
	UnconstrainedRefColumns []string
}

type ProtoSQLMapping struct {
	// Proto is the field shape as declared in the message ("string",
	// "optional <scalar>", "repeated enum", "map<K, scalar>").
	Proto string
	// SQL is the column the birth migration emits for it.
	SQL string
	// Notes is the one-line qualification, or "" when there is none.
	Notes string
}