Skip to content

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 ​

go
type Applied struct {
	State gsm.State

	Position int64
}

Applied is the outcome of applying one governed event.

type Applier ​

go
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 ​

go
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 ​

go
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 ​

go
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 ​

go
type EventToolConfig struct {
	Name string

	Description string

	Event string

	PolicyDigest string

	Attested bool

	Safety agent.Safety

	Options []agent.ToolOption
}

EventToolConfig configures EventTool.

type FedApplied ​

go
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 ​

go
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 ​

go
type FederatedEventToolConfig struct {
	Name string

	Description string

	Registry string

	Event string

	Safety agent.Safety

	Options []agent.ToolOption
}

FederatedEventToolConfig configures FederatedEventTool.

type FederatedGovernor ​

go
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 ​

go
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 ​

go
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 ​

go
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 ​

go
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 ​

go
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 ​

go
type Vote struct {
	Voter    string `json:"voter"`
	Decision string `json:"decision"`
}

Vote is one voter's recorded decision.

type Voter ​

go
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.

Apache-2.0 licensed.