govern

type Applied ¶ added in v0.5.0

type Applied struct {
	// State is the shared normal form after the event.
	State gsm.State
	// Position is the event's place in the order State is a replay of: its position in the shared
	// EventLog for a log-backed governor, or in the governor's own sequence for the in-memory
	// Governor. Replaying the events at positions [0, Position] from the initial state through the
	// same policy reproduces State exactly, which is what lets an auditor check a recorded state.
	Position int64
}

Applied is the outcome of applying one governed event.

type Applier ¶

type Applier interface {
	// Apply applies event as a new action, once per call.
	Apply(ctx context.Context, event string) (Applied, error)
	// ApplyOnce applies event at most once per id. A later call with the same id applies nothing
	// and returns what the first call applied: the same position, and the state replayed through
	// it. Reusing an id with a different event, or an empty id, is an ErrConfig error. EventTool
	// keys it by the tool call, so a call that runs again (its process died after applying the
	// event but before the call's result was recorded) does not apply its event twice.
	ApplyOnce(ctx context.Context, id, event string) (Applied, error)
	// State returns the governor's current view of the shared state. For a log-backed governor
	// it is as of the last Apply or Sync; other processes' later appends are folded in by the
	// next one.
	State() gsm.State
}

Applier applies a named governed event to shared state. Both the in-memory Governor and the log-backed PersistentGovernor satisfy it, so EventTool works with either.

type ConfluenceCertificate ¶

type ConfluenceCertificate struct {
	Machine      string `json:"machine"`       // name of the gsm machine the certificate is about
	PolicyDigest string `json:"policy_digest"` // stable identifier of the policy this certificate certifies

	// Converges is the headline: WFC && CC. True means every interleaving of events reaches the
	// same normal form, proven exhaustively at build time.
	Converges bool `json:"converges"`

	// WFC (well-founded compensation): every repair chain terminates; MaxRepairLen is the longest
	// one found. CC (compensation commutativity): independent event pairs commute.
	WFC          bool `json:"wfc"`
	CC           bool `json:"cc"`
	MaxRepairLen int  `json:"max_repair_len"`

	// The CC evidence: how many independent pairs were checked, split into those discharged by
	// footprint-disjointness and those checked by brute force over all valid states.
	PairsTotal    int `json:"pairs_total"`
	PairsDisjoint int `json:"pairs_disjoint"`
	PairsBrute    int `json:"pairs_brute"`

	// States is the size of the state space the check ran over exhaustively.
	States int `json:"states"`

	// CompensationFree marks the CRDT fragment. CRDT.v (sibling proof repo) establishes that
	// CRDTs are exactly the compensation-free fragment of this theory: operations that always
	// preserve every invariant, so normalization never needs to repair. MaxRepairLen == 0 means
	// no state in the enumerated space ever triggered a repair, so the machine sits in that
	// fragment: it is a CRDT, needs no coordinator, and its convergent state can merge with other
	// CRDT infrastructure. A positive MaxRepairLen means the policy uses compensation and is
	// therefore strictly more expressive than any CRDT (the reason to run it here at all). The
	// classification is conservative: MaxRepairLen == 0 is a sound witness of the CRDT fragment;
	// a positive value means compensation is defined and may fire.
	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. gsm.Registry.Build runs the normalization-confluence check EXHAUSTIVELY over the enumerated state space (not sampled): WFC proves every compensation chain terminates, and CC proves every independent event pair commutes to the same normal form. By Newman's lemma those two local facts give global confluence, so applying a set of events in ANY order reaches the same valid state. This certificate is that result made portable.

Without it the guarantee lived only inside gsm's build step and was discarded at the Bide boundary; a run could prove which policy was used (audit) but not that the policy was provably convergent. Anchoring the certificate next to the policy leaf (see audit.RecordConvergence) closes that: an auditor verifies not merely "policy digest X was used" but "policy digest X is provably convergent, checked over N states".

func CertifyConvergence(rep *gsm.Report, policyDigest string) ConfluenceCertificate

func (c ConfluenceCertificate) Classification() string

func (c ConfluenceCertificate) Marshal() ([]byte, error)

func (c ConfluenceCertificate) String() string

type EventLog ¶

type EventLog interface {
	// Append records event at the end of entity's log under id and returns its position: the
	// number of the entity's events recorded before it. If entity's log already holds an append
	// with this id, Append records nothing and returns that append's position; if that append's
	// event differs from event, or id is empty, it returns an error wrapping agent.ErrConfig. It
	// must be safe to call concurrently from many processes, which must never be assigned the
	// same position, and concurrent appends with the same id must record one event.
	Append(ctx context.Context, entity, id, event string) (int64, error)
	// Events returns entity's events at positions from onward, in log order.
	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).

Positions are dense and never change. The first event appended for an entity is at position 0, and once a reader has seen the events at positions [0, n), every later read returns those same events first. Governors rely on this to fold other processes' events into their state in exactly the order an auditor will replay them.

Appends are idempotent by id. A governor gives every append an id (a random one for Apply, the caller's for ApplyOnce) and may send the same append again: a transport retries a request whose reply was lost, or a tool call runs again after its process died. The log records each (entity, id) once, so a repeated append cannot record its event twice.

type FedApplied ¶ added in v0.5.0

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. Replaying the log's events at positions [0, Position] from the initial federated state reproduces State.

type FederatedApplier ¶

type FederatedApplier interface {
	// Apply applies event to registry as a new action, once per call.
	Apply(ctx context.Context, registry, event string) (FedApplied, error)
	// ApplyOnce applies event to registry at most once per id, like Applier.ApplyOnce: a later
	// call with the same id applies nothing and returns the first call's position and the state
	// replayed through it.
	ApplyOnce(ctx context.Context, id, registry, event string) (FedApplied, error)
	// State returns the governor's view of the federated state as of its last Apply or Sync.
	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 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. Each applied event is appended to the log as a (registry, event) pair, and the governor's state is the log replayed through the federated machine: before answering, Apply folds in every event the log holds up to and including its own, in log order, including other processes' events. So any number of processes sharing the log act on the same federated state, and a recorded state matches an auditor's replay of the log.

Cross-registry conflicts resolve WITHOUT coordination via the authority argument (paper §8.3): a source registry deterministically fixes its targets' shared components, so a target-side event that collides with its source is overwritten on the next ρ_Fed. This is the "distributed compensating agents across ownership boundaries" tier: each component registry is an organization or agent subtree, and morphisms are the cross-org constraints.

func NewFederated(ctx context.Context, m *gsm.FedMachine, log EventLog, entity string, initial gsm.FedState) (*FederatedGovernor, error)

func (fg *FederatedGovernor) Apply(ctx context.Context, registry, event string) (FedApplied, error)

func (fg *FederatedGovernor) ApplyOnce(ctx context.Context, id, registry, event string) (FedApplied, error)

func (fg *FederatedGovernor) State() gsm.FedState

func (fg *FederatedGovernor) Sync(ctx context.Context) (gsm.FedState, error)

type Governor ¶

type Governor struct {
	// contains filtered or unexported fields
}

Governor applies agents' events to one in-memory, gsm-governed state. Apply is convergent and thread-safe: because the machine was verified at Build time (WFC + CC), any order of the same event set lands on the same valid normal form. Its state lives only in this process; use a PersistentGovernor over a shared EventLog when several processes act on the same state.

func New(m *gsm.Machine, initial gsm.State) *Governor

func (g *Governor) Apply(_ context.Context, event string) (Applied, error)

func (g *Governor) ApplyOnce(_ context.Context, id, event string) (Applied, error)

func (g *Governor) State() gsm.State

type MemEventLog ¶

type MemEventLog struct {
	// contains filtered or unexported fields
}

MemEventLog is an in-memory EventLog for tests/local dev.

func NewMemEventLog() *MemEventLog

func (l *MemEventLog) Append(_ context.Context, entity, id, event string) (int64, error)

func (l *MemEventLog) Events(_ context.Context, entity string, from int64) ([]string, error)

type PersistentGovernor ¶

type PersistentGovernor struct {
	// contains filtered or unexported fields
}

PersistentGovernor is a governor over a shared, durable EventLog. Every event is appended to the log, and the governor's state is the log replayed through the machine, so any number of processes sharing the log act on the same state: before answering, Apply folds in every event the log holds up to and including its own, in log order, including other processes' events. The state an Apply returns is therefore exactly what an auditor gets by replaying the shared log through that event's position.

func NewPersistent(ctx context.Context, m *gsm.Machine, log EventLog, entity string, initial gsm.State) (*PersistentGovernor, error)

func (pg *PersistentGovernor) Apply(ctx context.Context, event string) (Applied, error)

func (pg *PersistentGovernor) ApplyOnce(ctx context.Context, id, event string) (Applied, error)

func (pg *PersistentGovernor) State() gsm.State

func (pg *PersistentGovernor) Sync(ctx context.Context) (gsm.State, error)

type QuorumResult ¶

type QuorumResult struct {
	Decision string `json:"decision"`  // the plurality decision; on a tie, the lexically smallest tied label (a placeholder, and Agreed is false)
	VotesFor int    `json:"votes_for"` // how many voters chose Decision
	Total    int    `json:"total"`     // number of voters that successfully voted
	Agreed   bool   `json:"agreed"`    // VotesFor >= k and no tie for the most votes (statistical signal, not a proof)
	Votes    []Vote `json:"votes"`     // every recorded vote, in voter order
}

QuorumResult is the tally over the votes. Decision is the plurality value (the decision the most voters chose); VotesFor is how many voters chose it; Total is the number of voters that voted; Agreed reports whether VotesFor >= k and no other decision has as many votes (a tie for the most votes is never agreement). Votes carries every recorded vote in voter order.

Agreed is the statistical signal, not a proof. The provable object is the gate a caller builds from VotesFor: seed votes_for into a gsm invariant that admits the commit only when votes_for >= k (see examples/quorum), and the k-of-n requirement is then machine-checked over every possible count. Whether the agreed Decision is correct is not certified here: correlated model errors mean agreement is not statistical independence, so a quorum lowers single-model risk without certifying the answer.

func Quorum(ctx context.Context, store agent.Durable, runID, name string, k int, voters ...Voter) (QuorumResult, error)

type Vote ¶

type Vote struct {
	Voter    string `json:"voter"`    // the voter that cast this decision
	Decision string `json:"decision"` // the normalized decision label the voter chose
}

Vote is one voter's recorded decision. It is the provenance the audit trail commits to.

type Voter ¶

type Voter struct {
	Name   string                                // identifies who voted; part of the vote's step name, so non-empty and unique per Quorum call
	Decide func(context.Context) (string, error) // produces this voter's normalized decision label
}

Voter is one named unit that produces a normalized decision. Name identifies who voted (a model, a provider/version, or any principal), so the recorded vote shows not just the tally but who voted how; it is part of the vote's durable step name, so it must be non-empty and unique across the voters in one Quorum call. Decide returns a discrete decision string; the caller keeps the model call and its parsing inside Decide, so Quorum stays model-agnostic and every vote is already a comparable, normalized value. Free-form prose cannot be quorumed: Decide must map to a small set of labels (an enum, a yes/no, a chosen action). Decide must have no side effects: a vote not yet recorded when the process dies is cast again on resume.