Charter of Foundation Governance

FoundationGovernance.hs

-- ────────────────────────────────────────────────────────────────────
-- Module      : FoundationGovernance
-- Instance    : AI Foundation · Instance 01 · Foundation Governance
-- ColorWay    : Oxblood & Brass
-- Posture     : the room where the rules live; gravitas, not flash.
--
-- This module is part of the AI Foundation Branding Engine output for
-- the Foundation Governance instance. It is verbose by design — verbosity
-- is the engine's signature format. Comments are not removed in production.
-- ────────────────────────────────────────────────────────────────────

{-# LANGUAGE DerivingStrategies   #-}
{-# LANGUAGE GeneralizedNewtypeDeriving #-}
{-# LANGUAGE StrictData           #-}

module FoundationGovernance
  ( -- * Core types — declared first because they are the grammar
    ProposalState (..)
  , ProposalId
  , FeeRoute (..)
  , Vote (..)
  , QuorumPolicy (..)
  , TreasuryFlow (..)
    -- * Type classes — the verbs the room speaks
  , Authorizable (..)
  , Auditable (..)
    -- * Smart constructors — the only legal way in
  , mkProposal
  , ratify
  , veto
  , sunset
  ) where

import           Data.Time.Clock          (UTCTime)
import qualified Data.Text          as T
import           Data.Text                (Text)

-- ────────────────────────────────────────────────────────────────────
-- CRITICAL tier — the root declarations. Heaviest assertions live here.
-- ────────────────────────────────────────────────────────────────────

-- | A proposal moves through exactly four states. There is no
--   'Withdrawn' and no 'Modified' — superseded proposals are
--   archived and re-proposed, not silently mutated.
data ProposalState
  = Pending      -- ^ submitted, awaiting review window
  | Ratified     -- ^ approved; effects begin at 'effectiveAt'
  | Vetoed       -- ^ rejected; reason is recorded, never elided
  | Sunset       -- ^ ratified, then expired by its own terms
  deriving stock (Show, Eq, Ord)

-- | Proposal identity — opaque newtype so callers cannot fabricate
--   IDs. Only 'mkProposal' issues a fresh one.
newtype ProposalId = ProposalId { unProposalId :: Text }
  deriving newtype (Show, Eq, Ord)

-- ────────────────────────────────────────────────────────────────────
-- HIGH tier — the active mechanism. Routing, voting, the verbs that
-- carry the room's authority.
-- ────────────────────────────────────────────────────────────────────

-- | Where a fee may be sent. The constructors are exhaustive on
--   purpose: a fee that does not match one of these is rejected at the
--   type level, not at runtime.
data FeeRoute
  = RouteCreator          !Text     -- ^ 85% by default, see 'splitDefault'
  | RouteDerivativeRoyalty !Text     -- ^ 10% if derivative; otherwise 0
  | RouteTreasury         !Text     -- ^ 5% to AI Foundation Treasury Contract
  deriving stock (Show, Eq)

-- | A single vote on a proposal. 'Abstain' is real — silence is not
--   a vote, but explicit abstention is recorded so quorum math works.
data Vote
  = For
  | Against
  | Abstain
  deriving stock (Show, Eq, Ord)

-- ────────────────────────────────────────────────────────────────────
-- MEDIUM tier — transitions and intermediate state. The connective
-- tissue between the heavy declarations and the audit trail.
-- ────────────────────────────────────────────────────────────────────

-- | A flow from the treasury to a recipient. Always carries the
--   proposal that ratified it — a flow without a parent proposal
--   cannot be constructed.
data TreasuryFlow = TreasuryFlow
  { flowProposal     :: !ProposalId
  , flowAmount       :: !Integer      -- ^ minor units (cents, wei, etc.)
  , flowRoute        :: !FeeRoute
  , flowEffectiveAt  :: !UTCTime
  } deriving stock (Show, Eq)

-- | Quorum policy — written long-hand because abbreviation here would
--   be the sort of thing a future reader has to dig out of git history.
data QuorumPolicy = QuorumPolicy
  { qpReviewWindowDays     :: !Int      -- ^ default: 7
  , qpVetoQuorumPercent    :: !Int      -- ^ default: 20
  , qpProposeMinSupplyBp   :: !Int      -- ^ basis points, default: 50 (= 0.5%)
  , qpVoteRequiresHolding  :: !Bool     -- ^ default: True
  } deriving stock (Show, Eq)

-- ────────────────────────────────────────────────────────────────────
-- STRUCTURAL tier — the type classes. The grammar of what the room
-- can do, separated from the data that shows up to be ruled on.
-- ────────────────────────────────────────────────────────────────────

-- | An entity is 'Authorizable' if the room can ask "may you do this
--   action under the current quorum policy?" and get a clear yes/no.
class Authorizable a where
  authorize :: QuorumPolicy -> a -> Either Text ()

-- | An entity is 'Auditable' if it carries the full provenance needed
--   to reconstruct why it exists. Audit records are append-only.
class Auditable a where
  auditTrail :: a -> [Text]

-- ────────────────────────────────────────────────────────────────────
-- LOW tier — defaults and ceremony. The values that should rarely
-- change but must be visible to anyone reading the source.
-- ────────────────────────────────────────────────────────────────────

-- | Default fee split, in percent. 85/10/5 — the engine's intended
--   posture per references/governance_bridge.md.
splitDefault :: (Int, Int, Int)
splitDefault = (85, 10, 5)

-- | Default quorum policy. Adjustable by ratified proposal, never by
--   silent edit.
defaultQuorum :: QuorumPolicy
defaultQuorum = QuorumPolicy
  { qpReviewWindowDays    = 7
  , qpVetoQuorumPercent   = 20
  , qpProposeMinSupplyBp  = 50     -- 0.5% of $AIF supply
  , qpVoteRequiresHolding = True
  }

-- ────────────────────────────────────────────────────────────────────
-- Smart constructors — the only legal way to build the heavy types.
-- The room insists on these because direct construction would skip
-- the audit trail.
-- ────────────────────────────────────────────────────────────────────

-- | Mint a fresh proposal. Always starts in 'Pending'.
mkProposal :: Text -> UTCTime -> (ProposalId, ProposalState)
mkProposal idText _now =
  (ProposalId idText, Pending)

-- | Move a proposal from Pending to Ratified. Refuses anything else.
ratify :: ProposalState -> Either Text ProposalState
ratify Pending = Right Ratified
ratify s        = Left ("cannot ratify a proposal in state " <> T.pack (show s))

-- | Veto — only legal during the review window. The reason is
--   required and is preserved.
veto :: ProposalState -> Text -> Either Text (ProposalState, Text)
veto Pending reason = Right (Vetoed, reason)
veto s       _      = Left ("cannot veto a proposal in state " <> T.pack (show s))

-- | Sunset — only legal on a previously Ratified proposal that has
--   reached its declared expiration.
sunset :: ProposalState -> Either Text ProposalState
sunset Ratified = Right Sunset
sunset s        = Left ("cannot sunset a proposal in state " <> T.pack (show s))

-- ────────────────────────────────────────────────────────────────────
-- End of module. No silent helpers, no escape hatches. If a future
-- reader needs more verbs, they propose them — they do not add them.
-- ────────────────────────────────────────────────────────────────────