migration

type ApplyOutcome struct {
	AppliedDrops       []string // destructive keys applied (explicitly approved)
	GatedDrops         []string // destructive keys present but NOT approved (drift)
	UnmatchedApprovals []string // approved keys that matched no destructive op
	// ExternalDrift are consumer-owned objects (no schema version ever declared
	// them — ENG-9) present in the database but out of migration scope: never
	// proposed as drops, never approvable, left untouched.
	ExternalDrift []string
	// Unapplied lists DECLARED operations that are STILL PENDING after the apply,
	// computed by RE-INTROSPECTING the live database — never by trusting the
	// executor's own log (ENG-13). A non-empty Unapplied means declared and applied
	// have DIVERGED and the apply is PARTIAL: it must never be reported as success.
	//
	// This is the class-level guard, not a per-operation one: whatever the reason an
	// operation did not land (a tolerated foreign-key failure, a rename skipped
	// because its target already existed, a future tolerant path nobody has written
	// yet), the verification sees the DATABASE and reports the gap.
	Unapplied []string
	// UnvalidatedFKs lists foreign keys that were added but left NOT VALID because
	// pre-existing rows violate them. They DO protect every new write; the historical
	// rows need fixing, then a manual VALIDATE. Not a divergence (the constraint
	// exists), so it does not make the apply partial — but it is reported, never
	// only logged.
	UnvalidatedFKs []string
	// NoChange is true when NO DDL was applied — the schema was already converged, or
	// the only pending operations were gated drops. It is the noop signal the
	// multi-tenant orchestrator uses to distinguish an "already up to date" tenant
	// from one it actually migrated.
	NoChange bool
}

type DestructiveImpact struct {
	Key      string `json:"key"`
	Kind     string `json:"kind"`
	Tenants  int    `json:"tenants"`   // tenants where this drop appears
	RowsLost int64  `json:"rows_lost"` // total rows lost across those tenants
}

type DestructiveOp struct {
	Key       string `json:"key"`        // approval token: "<table>" or "<table>.<column>"
	Kind      string `json:"kind"`       // "table" | "column"
	Table     string `json:"table"`      // the (post-rename) table name
	Column    string `json:"column"`     // "" for a table drop
	RowsLost  int64  `json:"rows_lost"`  // rows whose data is destroyed (table: all rows; column: rows with a non-null value)
	TableRows int64  `json:"table_rows"` // total rows in the table (context)
	Approved  bool   `json:"approved"`   // whether this op's key is in the supplied approval set
	Summary   string `json:"summary"`    // human one-liner with the impact
}

type FanoutOptions struct {
	// Schema is the desired schema applied to EVERY targeted tenant.
	Schema *schema.APISchema
	// TenantIDs is an explicit subset; empty means ALL tenants in public.tenants.
	// The caller (CLI) must opt into "all" deliberately — it never defaults silently.
	TenantIDs []string
	// ApprovedDrops are destructive-drop keys approved for EVERY targeted tenant
	// (a mass drop). Empty (the default) is additive: every drop is gated.
	ApprovedDrops []string
	// DryRun classifies + measures impact without applying or persisting anything.
	DryRun bool
	// OnTenant, if set, is called after each tenant completes (for CLI streaming).
	OnTenant func(TenantFanoutResult)
}

type FanoutResult struct {
	RunID          string               `json:"run_id"`
	DryRun         bool                 `json:"dry_run"`
	Total          int                  `json:"total"`
	Applied        int                  `json:"applied"`
	Noop           int                  `json:"noop"`
	Failed         int                  `json:"failed"`
	MissingTenants []string             `json:"missing_tenants,omitempty"` // requested ids not in public.tenants
	Results        []TenantFanoutResult `json:"results"`
}

type FanoutStatus string

type MigrationWorker struct {

	// BlockTime is how long XReadGroup waits for new messages before looping.
	// Default: 5s. Set to a smaller value in tests.
	BlockTime time.Duration

	// BackoffBase is the unit delay before re-enqueueing a failed job.
	// Delays: BackoffBase * 1, BackoffBase * 2, BackoffBase * 4 (exponential).
	// Default: 1s. Set to a smaller value in tests.
	BackoffBase time.Duration

	// LockRetryDelay is how long to wait before re-enqueueing a job whose tenant
	// advisory lock is held by another worker. Default: 2s.
	LockRetryDelay time.Duration

	// ConsumerName identifies this worker in the Redis consumer group.
	// Must be unique per running worker instance. Default: "worker-1".
	ConsumerName string
	// contains filtered or unexported fields
}

type Preview struct {
	PGSchema string `json:"pg_schema"`
	// Empty is true when the schema is already converged — nothing to do.
	Empty bool `json:"empty"`
	// Apply are the SAFE operations that will run (creates, adds, alters, renames, FK
	// adds, and any FK drop required as a consequence of an approved table drop). The
	// data-losing drops are NOT here — they live in Destructive with their impact.
	Apply []string `json:"apply,omitempty"`
	// Destructive are the data-losing drops with impact and approval status. A drop is
	// applied only when Approved is true; otherwise it is gated (drift).
	Destructive []DestructiveOp `json:"destructive,omitempty"`
	// Drift are the SAFE drops (index/constraint removals) left as additive drift —
	// not approvable in v1, they simply stay.
	Drift []string `json:"drift,omitempty"`
	// Concerns are backfill/transformational risks on PRE-EXISTING tables (e.g. a NOT
	// NULL added over populated data), surfaced before applying.
	Concerns []string `json:"concerns,omitempty"`
	// UnmatchedApprovals are supplied approval tokens that matched no destructive op
	// in this plan (a typo, or an already-applied drop).
	UnmatchedApprovals []string `json:"unmatched_approvals,omitempty"`
	// External are consumer-owned objects (no deployed schema version ever declared
	// them — ENG-9): present in the database, out of migration scope, never proposed
	// as drops and never approvable. Informative only.
	External []string `json:"external,omitempty"`
}

type TenantFanoutResult struct {
	TenantID     string       `json:"tenant_id"`
	PGSchema     string       `json:"pg_schema"`
	Status       FanoutStatus `json:"status"`
	AppliedDrops []string     `json:"applied_drops,omitempty"`
	GatedDrops   []string     `json:"gated_drops,omitempty"`
	Error        string       `json:"error,omitempty"`
	DurationMS   int64        `json:"duration_ms"`
	// Preview is populated on a dry run (the classified plan + per-drop impact).
	Preview *Preview `json:"preview,omitempty"`
}