package runtimeports

import (
	"database/sql"

	contractcontrolplane "github.com/pingcap-inc/nexuscrm-contract/pkg/controlplane"
)

// BootstrapStateStore is the composition seam for the control-plane's reads and
// writes of the _System_BootstrapState receipt rows: the full-ApplyAll lifecycle
// marker, the auto-start classifier, and the per-release warm-upgrade backfill
// receipts.
//
// The concrete implementation (bootstate.BootstrapStateStoreImpl) lives beside
// the canonical bootstrap-state functions and delegates to them directly.
// The port exists so control-plane consumers depend on this neutral interface
// instead of importing backend/internal/bootstrap for these state reads/writes. The
// concrete impl is wired at the runtime composition root (pkg/serverruntime).
//
// Every underlying bootstrap function takes a *sql.DB (it reads/writes the
// _System_BootstrapState table) and is stateless, so the port methods MIRROR
// those signatures EXACTLY — the *sql.DB is bound per call, not at construction,
// keeping the impl and the package-init seam default stateless.
//
// The classifier's return shape (ControlPlaneAutoStartDecision and its
// ControlPlaneAutoStartAction enum) is the neutral, pure type relocated to
// nexuscrm-contract/pkg/controlplane, so this leaf package references it without
// importing internal/bootstrap.
type BootstrapStateStore interface {
	// ClassifyControlPlaneAutoStart is the single fail-closed classifier for the
	// container auto-start apply decision. Any read error is returned, never
	// folded into a mutating default.
	ClassifyControlPlaneAutoStart(rawDB *sql.DB) (contractcontrolplane.ControlPlaneAutoStartDecision, error)

	// MarkControlPlaneApplyAllRunning unconditionally stamps the full-ApplyAll
	// marker to running before a mutating ApplyAll attempt does work.
	MarkControlPlaneApplyAllRunning(rawDB *sql.DB) error
	// MarkControlPlaneApplyAllCompleted restores the full-ApplyAll completion
	// marker. It is the only writer that may stamp completed.
	MarkControlPlaneApplyAllCompleted(rawDB *sql.DB) error
	// MarkControlPlaneApplyAllFailed records a failed full-ApplyAll attempt.
	MarkControlPlaneApplyAllFailed(rawDB *sql.DB, applyErr error) error
	// IsControlPlaneApplyAllFinalizationRecoverable recognizes only a durable
	// terminal-verification receipt (plus the exact predecessor final-lock
	// failure marker) that may enter exact-candidate recovery.
	IsControlPlaneApplyAllFinalizationRecoverable(rawDB *sql.DB) (bool, error)
	// MarkControlPlaneApplyAllFinalizationReady records that full ApplyAll and
	// its terminal gates passed. It is not a serving-ready completion marker.
	MarkControlPlaneApplyAllFinalizationReady(rawDB *sql.DB) error
	// MarkControlPlaneApplyAllInvalidated downgrades a completed full-ApplyAll
	// marker before a narrower control-plane mutator writes.
	MarkControlPlaneApplyAllInvalidated(rawDB *sql.DB, operation string) error

	// IsConnectorPushLegacyMirrorBackfillCompleted reports whether this release's
	// legacy PushToConnector mirror materialization backfill has run.
	IsConnectorPushLegacyMirrorBackfillCompleted(rawDB *sql.DB) (bool, error)
	// IsWebhookSecretKeyReadProtectionBackfillCompleted reports whether this
	// release's webhook SecretKey read-protection backfill has run.
	IsWebhookSecretKeyReadProtectionBackfillCompleted(rawDB *sql.DB) (bool, error)
	// IsConnectorEventEnqueueOrdinalBackfillCompleted reports whether this
	// release's connector event enqueue-ordinal repair has run and converged.
	IsConnectorEventEnqueueOrdinalBackfillCompleted(rawDB *sql.DB) (bool, error)
	// IsConnectorEventSourceLaneBackfillCompleted reports whether this release's
	// connector event source-lane materialization has run and converged.
	IsConnectorEventSourceLaneBackfillCompleted(rawDB *sql.DB) (bool, error)
	// IsListViewLegacyCutoverCompleted reports whether this release's list-view
	// ownership cutover has run and converged.
	IsListViewLegacyCutoverCompleted(rawDB *sql.DB) (bool, error)

	// MarkConnectorPushLegacyMirrorBackfillCompleted stamps the legacy mirror
	// backfill receipt.
	MarkConnectorPushLegacyMirrorBackfillCompleted(rawDB *sql.DB) error
	// MarkWebhookSecretKeyReadProtectionBackfillCompleted stamps the webhook
	// SecretKey read-protection backfill receipt.
	MarkWebhookSecretKeyReadProtectionBackfillCompleted(rawDB *sql.DB) error
	// MarkConnectorEventEnqueueOrdinalBackfillCompleted stamps the connector
	// event enqueue-ordinal backfill receipt.
	MarkConnectorEventEnqueueOrdinalBackfillCompleted(rawDB *sql.DB) error
	// MarkConnectorEventSourceLaneBackfillCompleted stamps the connector event
	// source-lane backfill receipt.
	MarkConnectorEventSourceLaneBackfillCompleted(rawDB *sql.DB) error
	// MarkListViewLegacyCutoverCompleted stamps the list-view ownership cutover
	// receipt.
	MarkListViewLegacyCutoverCompleted(rawDB *sql.DB) error
}