scope

Documentation

Overview

Package scope is the I2.5 scope FSM: the typed lifecycle of an authorization grant created by `aiwf authorize`.

A scope is the kernel's unit of "this work is authorized." Its state is computed by walking commits forward from the authorize commit and applying transitions in commit order. The scope's "frontmatter" is the trailer set on the original authorize commit; transitions are themselves commits with trailers.

State machine (closed set: active | paused | ended):

authorize commit lands → state: active
   ↓
active ──pause──→ paused ──resume──→ active ──...
   ↓                              ↓
ended ←──── (auto: terminal-promote of the scope-entity carries
             aiwf-scope-ends: <auth-sha>)

Legal transitions are enforced by IsLegalScopeTransition. Ended is terminal: un-canceling the scope-entity does not resurrect a previously-ended scope; the human must issue a new authorization.

Reference: docs/pocv3/design/provenance-model.md §"Scope as a first-class FSM".

Index

• func IsLegalScopeTransition(from, to State) bool
• type Commit
• type Event
• type Scope
  • func LoadScope(authSHA string, history []Commit) (*Scope, error)
• type State

Functions

func IsLegalScopeTransition

func IsLegalScopeTransition(from, to State) bool

IsLegalScopeTransition reports whether moving from -> to is allowed by the FSM. Self-loops (active→active, paused→paused) are not legal — every transition is meaningful. Ended is terminal.

Types

type Commit

type Commit struct {
	SHA      string
	Trailers []gitops.Trailer
}

Commit is the minimal git-commit shape the scope package consumes: a SHA plus the trailer key/value set extracted from the commit message. Adapters in cmd/aiwf wrap gitops.HeadTrailers / git log output into this shape so the FSM stays I/O-free and unit-testable.

type Event

type Event struct {
	SHA    string
	State  State
	Reason string
}

Event is one transition recorded against a scope: the commit SHA that produced it, the resulting state, and (for pause/resume) the reason text from the aiwf-reason: trailer when present.

type Scope

type Scope struct {
	AuthSHA   string
	Entity    string
	Agent     string
	Principal string
	State     State
	Events    []Event
}

Scope is the materialized lifecycle of one authorization grant. AuthSHA is the SHA of the originating authorize commit; Entity is the scope-entity id (the value of aiwf-entity: on the authorize commit); Agent is the value of aiwf-to: (the agent the scope authorizes); Principal is the human who issued the authorization (= aiwf-actor: on the authorize commit). State is the current state derived from Events; Events lists every transition the scope has gone through, in commit order.

func LoadScope

func LoadScope(authSHA string, history []Commit) (*Scope, error)

LoadScope reconstructs a scope's lifecycle by walking history forward from the authorize commit. authSHA names the originating commit; history is the commit sequence in chronological order (oldest first). The walk stops at the first commit that ends the scope (an aiwf-scope-ends: trailer naming authSHA).

Errors:

• the authorize commit (history[0]'s SHA == authSHA) must carry aiwf-verb: authorize and aiwf-scope: opened, else the SHA is not actually a scope opener.
• a pause/resume on a state that doesn't allow it produces a malformed-history error (the FSM was driven by hand-edited commits that bypassed the verb).

The function is pure: no I/O, no git subprocess. Adapters in cmd/aiwf produce the Commit slice via gitops.

type State

type State string

State is the closed set of scope lifecycle states. A scope is `active` from the moment its authorize commit lands; pause/resume transitions cycle it between `active` and `paused`; either may transition to the terminal `ended` when the scope-entity reaches a terminal status.

const (
	StateActive State = "active"
	StatePaused State = "paused"
	StateEnded  State = "ended"
)

State values.