docs(bootstrap): note the two latent invariants red flagged (X-Chain DAG-sync gate; monotonic bootstrapped state)

Documentation-only; no behavior change (v1.32.11 image unaffected). Red review of
the v1.32.11 diff: 0 critical/high/medium, recommendation SHIP.

Co-authored-by: Hanzo Dev <dev@hanzo.ai>

chains/manager_authz.go

@@ -123,8 +123,14 @@ func (m *manager) authorizeChainActivation(chainID ids.ID) (authorized bool, rea
 	// authorization from an NFT held at an address it does not control.
 
 	// The gate consults the X-Chain UTXO set, so the X-Chain must already be
-	// bootstrapped (created and tracked) on this node. If not, we cannot decide
-	// yet — signal the caller to defer.
+	// bootstrapped on this node. IsBootstrapped now keys on REAL convergence
+	// (sb.Bootstrapped), not mere presence — safe here because X-Chain is a DAG
+	// chain marked bootstrapped SYNCHRONOUSLY inside createChain (Engine == nil
+	// path) before the sequential chain-creator dequeues any re-pushed gated chain,
+	// so IsBootstrapped(X) is already true when a gated chain re-runs. INVARIANT: if
+	// X-Chain is ever linearized into an engine chain (async Bootstrapped via
+	// monitorBootstrap), retryPendingGatedChains must be made to re-drain after X
+	// converges, else gated chains park forever. If not bootstrapped yet, defer.
 	if !m.IsBootstrapped(m.XChainID) {
 		return false, false
 	}

nets/net.go

@@ -75,6 +75,14 @@ func (s *chain) IsBootstrapped() bool {
 	return s.bootstrapping.Len() == 0
 }
 
+// IsChainBootstrapped assumes MONOTONIC per-process bootstrapped state: a chain
+// only ever moves bootstrapping→bootstrapped (Bootstrapped is forward-only and
+// AddChain refuses to re-add a chain already in either set), so this signal — and
+// the Bootstrapping() health check that shares the set — never report stale-true.
+// INVARIANT: if a future path ever moves a live chain BACK to bootstrapping (e.g.
+// SetState(Bootstrapping) on a running chain) it MUST remove the chainID from
+// bootstrapped, or both this signal and the readiness health check will report a
+// re-syncing chain as still bootstrapped.
 func (s *chain) IsChainBootstrapped(chainID ids.ID) bool {
 	s.lock.RLock()
 	defer s.lock.RUnlock()