Module github.com/bide-ai/bide/govern
Go module github.com/bide-ai/bide/govern; all modules.
govern
github.com/bide-ai/bide/govern · pkg.go.dev · Stability: experimental
Package govern is the Tier-2 (distributed / concurrent) compensating-agent layer: it integrates the gsm "Governed State Machine" library so that MULTIPLE concurrent agents mutating SHARED state converge to the same valid state regardless of interleaving, as certified by gsm's build-time normalization-confluence verification (WFC + CC).
Functions
func EventTool(gov Applier, cfg EventToolConfig) agent.Tool: EventTool gives an agent a GOVERNED action: when the agent's LLM calls it, cfg.Event is applied to the shared governed state (convergent + thread-safe).func FederatedEventTool(gov FederatedApplier, cfg FederatedEventToolConfig) agent.Tool: FederatedEventTool gives an agent a GOVERNED federated action: when the agent's LLM calls it, cfg.Event is applied to component cfg.Registry of the shared federation.func QuorumConfigStep(name string) string: QuorumConfigStep is the step name under which the quorum named name records its k and voters.func QuorumTallyStep(name string) string: QuorumTallyStep is the step name of the tally of the quorum named name.func QuorumVoteStep(name, voter string) string: QuorumVoteStep is the step name of voter's vote in the quorum named name.
type Applied
type Applied struct {
State gsm.State
Position int64
}Applied is the outcome of applying one governed event.
type Applier
type Applier interface {
Apply(ctx context.Context, event string) (Applied, error)
ApplyOnce(ctx context.Context, id, event string) (Applied, error)
State() gsm.State
}Applier applies a named governed event to shared state.
type ConfluenceCertificate
type ConfluenceCertificate struct {
Machine string `json:"machine"`
PolicyDigest string `json:"policy_digest"`
Converges bool `json:"converges"`
WFC bool `json:"wfc"`
CC bool `json:"cc"`
MaxRepairLen int `json:"max_repair_len"`
PairsTotal int `json:"pairs_total"`
PairsDisjoint int `json:"pairs_disjoint"`
PairsBrute int `json:"pairs_brute"`
PairsUndeclared int `json:"pairs_undeclared"`
CausalOrderRequired []EventPair `json:"causal_order_required"`
NotIdempotent []string `json:"not_idempotent"`
Saturations []Saturation `json:"saturations"`
States int `json:"states"`
CompensationFree bool `json:"compensation_free"`
}ConfluenceCertificate is the machine-checkable evidence that a governed policy converges, carried out of gsm's build-time verification and into the SDK so it can be surfaced to a user and anchored in the audit trail.
Constructors and functions
func CertifyConvergence(rep *gsm.Report, policyDigest string) ConfluenceCertificate: CertifyConvergence translates a gsm build Report and the policy's digest into a portable certificate.
Methods
func (c ConfluenceCertificate) Classification() string: Classification names the fragment the machine lives in, for a human-facing report.func (c ConfluenceCertificate) Marshal() ([]byte, error): Marshal serializes the certificate for anchoring as an audit leaf (see audit.RecordConvergence).func (c ConfluenceCertificate) String() string: String renders the certificate for a build log or CLI.
type EventLog
type EventLog interface {
Append(ctx context.Context, entity, id, event string) (int64, error)
Events(ctx context.Context, entity string, from int64) ([]string, error)
}EventLog is an append-only, totally ordered log of governed events per entity: the durable shared record several processes' governors act on (MemEventLog below; govern/sqlitelog, govern/postgreslog, and govern/redislog for durable backends).
type EventPair
type EventPair struct {
First string `json:"first"`
Second string `json:"second"`
}EventPair names two events, as gsm reports a pair that does not commute.
type EventToolConfig
type EventToolConfig struct {
Name string
Description string
Event string
PolicyDigest string
Attested bool
Safety agent.Safety
Options []agent.ToolOption
}EventToolConfig configures EventTool.
type FedApplied
type FedApplied struct {
State gsm.FedState
Position int64
}FedApplied is the outcome of applying one federated event: the federated normal form after it, and the event's position in the shared EventLog.
type FederatedApplier
type FederatedApplier interface {
Apply(ctx context.Context, registry, event string) (FedApplied, error)
ApplyOnce(ctx context.Context, id, registry, event string) (FedApplied, error)
State() gsm.FedState
}FederatedApplier is the federated analogue of Applier: it applies a named event to a named component registry of a gsm federation.
type FederatedEventToolConfig
type FederatedEventToolConfig struct {
Name string
Description string
Registry string
Event string
Safety agent.Safety
Options []agent.ToolOption
}FederatedEventToolConfig configures FederatedEventTool.
type FederatedGovernor
type FederatedGovernor struct {
// contains filtered or unexported fields
}FederatedGovernor is a governor over a gsm federation (multiple component registries linked by directed morphisms), backed by a shared, durable EventLog.
Constructors and functions
func NewFederated(ctx context.Context, m *gsm.FedMachine, log EventLog, entity string, initial gsm.FedState) (*FederatedGovernor, error): NewFederated constructs a federated governor over the entity's log and reconstructs its state by replaying the log from the initial federated state.
Methods
func (fg *FederatedGovernor) Apply(ctx context.Context, registry, event string) (FedApplied, error): Apply validates the (registry, event) against the federation, appends it to the shared log, then folds the log into the state up to and including its position.func (fg *FederatedGovernor) ApplyOnce(ctx context.Context, id, registry, event string) (FedApplied, error): ApplyOnce is Apply at most once per id, across every process sharing the log (see FederatedApplier).func (fg *FederatedGovernor) State() gsm.FedState: State returns the governor's view of the federated state as of its last Apply or Sync.func (fg *FederatedGovernor) Sync(ctx context.Context) (gsm.FedState, error): Sync folds every entry the log currently holds into the state and returns it, so the governor reflects other processes' events without applying one of its own.
type Governor
type Governor struct {
// contains filtered or unexported fields
}Governor applies agents' events to one in-memory, gsm-governed state.
Constructors and functions
func New(m *gsm.Machine, initial gsm.State) *Governor: New wraps a built, verified gsm.Machine with an initial state.
Methods
func (g *Governor) Apply(_ context.Context, event string) (Applied, error): Apply advances the shared state by one event (O(1) table lookup; compensation to a valid normal form is baked in).func (g *Governor) ApplyOnce(_ context.Context, id, event string) (Applied, error): ApplyOnce is Apply at most once per id (see Applier).func (g *Governor) State() gsm.State: State returns the current shared normal-form state.
type MemEventLog
type MemEventLog struct {
// contains filtered or unexported fields
}MemEventLog is an in-memory EventLog for tests/local dev.
Constructors and functions
func NewMemEventLog() *MemEventLog: NewMemEventLog returns an empty in-memory EventLog.
Methods
func (l *MemEventLog) Append(_ context.Context, entity, id, event string) (int64, error): Append records an event for the entity under id and returns its position, or returns the position already recorded for id.func (l *MemEventLog) Events(_ context.Context, entity string, from int64) ([]string, error): Events returns a copy of the entity's events at positions from onward.
type PersistentGovernor
type PersistentGovernor struct {
// contains filtered or unexported fields
}PersistentGovernor is a governor over a shared, durable EventLog.
Constructors and functions
func NewPersistent(ctx context.Context, m *gsm.Machine, log EventLog, entity string, initial gsm.State) (*PersistentGovernor, error): NewPersistent constructs a governor over the entity's log and reconstructs its state by replaying the log from the initial state.
Methods
func (pg *PersistentGovernor) Apply(ctx context.Context, event string) (Applied, error): Apply appends the event to the shared log, then folds the log into the state up to and including the event's position (so every earlier event, from any process, is applied first, in log order), and returns that state and position.func (pg *PersistentGovernor) ApplyOnce(ctx context.Context, id, event string) (Applied, error): ApplyOnce is Apply at most once per id (see Applier), across every process sharing the log: the id travels with the append, and the log records each id once.func (pg *PersistentGovernor) State() gsm.State: State returns the governor's view of the shared state as of its last Apply or Sync.func (pg *PersistentGovernor) Sync(ctx context.Context) (gsm.State, error): Sync folds every event the log currently holds into the state and returns it, so the governor reflects other processes' events without applying one of its own.
type QuorumResult
type QuorumResult struct {
Decision string `json:"decision"`
VotesFor int `json:"votes_for"`
Total int `json:"total"`
Agreed bool `json:"agreed"`
Votes []Vote `json:"votes"`
}QuorumResult is the tally over the votes.
Constructors and functions
func Quorum(ctx context.Context, store *agent.Journal, runID, name string, k int, voters ...Voter) (QuorumResult, error): Quorum fans the voters out concurrently and durably, tallies their normalized decisions, and returns the plurality decision with its count.
type Saturation
type Saturation struct {
Rule string `json:"rule"`
Var string `json:"var"`
States int `json:"states"`
}Saturation is a rule whose write was clamped into a variable's range (gsm.Saturation): the rule, the variable written, and on how many of the states Build checked.
type Vote
type Vote struct {
Voter string `json:"voter"`
Decision string `json:"decision"`
}Vote is one voter's recorded decision.
type Voter
type Voter struct {
Name string
Decide func(context.Context) (string, error)
}Voter is one named unit that produces a normalized decision.
govern/eventlogtest
github.com/bide-ai/bide/govern/eventlogtest · pkg.go.dev · Stability: experimental
Package eventlogtest checks that an implementation satisfies the govern.EventLog contract, so every adapter (in-memory, SQLite, Postgres, Redis, or your own) is held to the same guarantees a governor relies on: dense, unique positions under concurrent appends from separate processes, appends that are idempotent by id (so a retried append is recorded once), and a log that only ever grows at the end.
Functions
func Run(t *testing.T, open func(t *testing.T) govern.EventLog): Run runs the conformance suite.