workplan

package
v0.1.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 4, 2026 License: MIT Imports: 18 Imported by: 0

Documentation

Overview

Package workplan implements the storage, validation, and bounded mutations for the living-Saga v3 work-plan domain. It deliberately has no CLI, query, or server dependencies so those adapters can evolve independently.

Index

Constants

View Source
const (
	Version = 3
	RootDir = "___workplan"

	WaveSchema       = "https://changesaga.dev/schema/v3/wave.schema.json"
	WorkItemSchema   = "https://changesaga.dev/schema/v3/work-item.schema.json"
	DependencySchema = "https://changesaga.dev/schema/v3/dependency.schema.json"
	ContractSchema   = "https://changesaga.dev/schema/v3/contract.schema.json"
	RevisionSchema   = "https://changesaga.dev/schema/v3/workplan-revision.schema.json"
	EventSchema      = "https://changesaga.dev/schema/v3/workplan-event.schema.json"

	MaxWaves                = 10_000
	MaxWorkItems            = 20_000
	MaxDependencies         = 50_000
	MaxContracts            = 20_000
	MaxRevisionsPerResource = 10_000
	MaxEventsPerStream      = 50_000
	MaxRecordBytes          = 1 << 20
)

Variables

This section is empty.

Functions

func ContractEventURN

func ContractEventURN(sagaID, contractID, eventID string) (string, error)

func DependencySatisfied

func DependencySatisfied(plan Plan, dependencyID string) (bool, string)

DependencySatisfied evaluates only persisted work-plan facts. Wave order, wave lifecycle, workspace ancestry, and process liveness are intentionally absent from every condition.

func Load

func Load(root string) (Plan, Validation, error)

Load reads only saga.json and ___workplan. It never follows a symlink and never loads authored narrative/design bodies or diff atoms.

func MergeEventURN

func MergeEventURN(sagaID, itemID, eventID string) (string, error)

func ProgressEventURN

func ProgressEventURN(sagaID, itemID, eventID string) (string, error)

func WorkspaceEventURN

func WorkspaceEventURN(sagaID, itemID, eventID string) (string, error)

Types

type Conflict

type Conflict struct {
	Kind     string   `json:"kind"`
	Resource string   `json:"resource"`
	Heads    []string `json:"heads"`
}

type Contract

type Contract struct {
	Identity
	Revisions       []ContractRevision `json:"-"`
	Heads           []string           `json:"-"`
	Events          []ContractEvent    `json:"-"`
	CurrentRevision *ContractRevision  `json:"-"`
	CurrentEvent    *ContractEvent     `json:"-"`
}

type ContractEvent

type ContractEvent struct {
	EventBase
	Contract string   `json:"contract"`
	State    string   `json:"state"`
	Evidence []string `json:"evidence"`
}

type ContractRevision

type ContractRevision struct {
	Schema        string    `json:"$schema"`
	Version       int       `json:"version"`
	ID            string    `json:"id"`
	Contract      string    `json:"contract"`
	Parents       []string  `json:"parents"`
	Kind          string    `json:"kind"`
	Provider      string    `json:"provider"`
	Consumer      string    `json:"consumer"`
	Statement     string    `json:"statement"`
	Acceptance    []string  `json:"acceptance"`
	CreatedAt     time.Time `json:"created_at"`
	RequestID     string    `json:"request_id,omitempty"`
	RequestDigest string    `json:"request_digest,omitempty"`
}

type Dependency

type Dependency struct {
	Schema        string              `json:"$schema"`
	Version       int                 `json:"version"`
	ID            string              `json:"id"`
	Prerequisite  string              `json:"prerequisite"`
	Dependent     string              `json:"dependent"`
	Condition     DependencyCondition `json:"condition"`
	Reason        string              `json:"reason"`
	CreatedAt     time.Time           `json:"created_at"`
	RequestID     string              `json:"request_id,omitempty"`
	RequestDigest string              `json:"request_digest,omitempty"`
}

type DependencyCondition

type DependencyCondition struct {
	Kind             string `json:"kind"`
	ContractRevision string `json:"contract_revision,omitempty"`
}

type EventBase

type EventBase struct {
	Schema        string    `json:"$schema"`
	Version       int       `json:"version"`
	ID            string    `json:"id"`
	Parents       []string  `json:"parents"`
	CreatedAt     time.Time `json:"created_at"`
	Summary       string    `json:"summary,omitempty"`
	RequestID     string    `json:"request_id,omitempty"`
	RequestDigest string    `json:"request_digest,omitempty"`
}

EventBase is shared by append-only state graphs. Parents are event URNs, never timestamps. Multiple current heads are retained as an explicit conflict; a reconciliation event names every head as its parents.

type Identity

type Identity struct {
	Schema    string    `json:"$schema"`
	Version   int       `json:"version"`
	ID        string    `json:"id"`
	CreatedAt time.Time `json:"created_at"`
}

type Issue

type Issue struct {
	Severity string `json:"severity"`
	Path     string `json:"path"`
	Message  string `json:"message"`
}

type MergeEvent

type MergeEvent struct {
	EventBase
	WorkItem  string `json:"work_item"`
	Unit      string `json:"unit"`
	State     string `json:"state"`
	HeadOID   string `json:"head_oid,omitempty"`
	MergeOID  string `json:"merge_oid,omitempty"`
	RevertOID string `json:"revert_oid,omitempty"`
}

type MergeUnit

type MergeUnit struct {
	ID           string `json:"id"`
	Repository   string `json:"repository"`
	SourceBranch string `json:"source_branch"`
	TargetBranch string `json:"target_branch"`
	Required     bool   `json:"required"`
}

type MutationResult

type MutationResult struct {
	URN      string   `json:"urn,omitempty"`
	Path     string   `json:"path,omitempty"`
	Created  []string `json:"created"`
	EventIDs []string `json:"event_ids"`
	Replayed bool     `json:"replayed"`
}

func CreateContract

func CreateContract(root, contractID string, revision ContractRevision, requestID string) (MutationResult, error)

func CreateDependency

func CreateDependency(root string, dependency Dependency, requestID string) (MutationResult, error)

func CreateWave

func CreateWave(root, waveID string, revision WaveRevision, requestID string) (MutationResult, error)

func CreateWorkItem

func CreateWorkItem(root, itemID string, revision WorkItemRevision, requestID string) (MutationResult, error)

func RecordContractState

func RecordContractState(root, contractID string, event ContractEvent, requestID string) (MutationResult, error)

func RecordMerge

func RecordMerge(root, itemID string, event MergeEvent, requestID string) (MutationResult, error)

func RecordProgress

func RecordProgress(root, itemID string, event ProgressEvent, requestID string) (MutationResult, error)

func RecordWorkspace

func RecordWorkspace(root, itemID string, event WorkspaceEvent, requestID string) (MutationResult, error)

func ReviseContract

func ReviseContract(root string, revision ContractRevision, requestID string) (MutationResult, error)

func ReviseWave

func ReviseWave(root string, revision WaveRevision, requestID string) (MutationResult, error)

func ReviseWorkItem

func ReviseWorkItem(root string, revision WorkItemRevision, requestID string) (MutationResult, error)

type Mutator

type Mutator struct {
	Now         func() time.Time
	LockTimeout time.Duration
}

Mutator provides deterministic clocks for tests/adapters while retaining the package-level helpers for ordinary callers.

func (Mutator) CreateContract

func (m Mutator) CreateContract(root, contractID string, revision ContractRevision, requestID string) (MutationResult, error)

func (Mutator) CreateDependency

func (m Mutator) CreateDependency(root string, dependency Dependency, requestID string) (MutationResult, error)

func (Mutator) CreateWave

func (m Mutator) CreateWave(root, waveID string, revision WaveRevision, requestID string) (MutationResult, error)

func (Mutator) CreateWorkItem

func (m Mutator) CreateWorkItem(root, itemID string, revision WorkItemRevision, requestID string) (MutationResult, error)

func (Mutator) RecordContractState

func (m Mutator) RecordContractState(root, contractID string, event ContractEvent, requestID string) (MutationResult, error)

func (Mutator) RecordMerge

func (m Mutator) RecordMerge(root, itemID string, event MergeEvent, requestID string) (MutationResult, error)

func (Mutator) RecordProgress

func (m Mutator) RecordProgress(root, itemID string, event ProgressEvent, requestID string) (MutationResult, error)

func (Mutator) RecordWorkspace

func (m Mutator) RecordWorkspace(root, itemID string, event WorkspaceEvent, requestID string) (MutationResult, error)

func (Mutator) ReviseContract

func (m Mutator) ReviseContract(root string, revision ContractRevision, requestID string) (MutationResult, error)

func (Mutator) ReviseWave

func (m Mutator) ReviseWave(root string, revision WaveRevision, requestID string) (MutationResult, error)

func (Mutator) ReviseWorkItem

func (m Mutator) ReviseWorkItem(root string, revision WorkItemRevision, requestID string) (MutationResult, error)

type Plan

type Plan struct {
	Root         string
	SagaID       string
	Waves        map[string]*Wave
	WorkItems    map[string]*WorkItem
	Dependencies map[string]*Dependency
	Contracts    map[string]*Contract
	Requests     map[string]RequestRecord
	Conflicts    []Conflict
}

type ProgressEvent

type ProgressEvent struct {
	EventBase
	WorkItem string `json:"work_item"`
	State    string `json:"state"`
	Reason   string `json:"reason,omitempty"`
}

type RequestRecord

type RequestRecord struct {
	Operation string
	Digest    string
	Resource  string
	EventID   string
	Path      string
}

type TouchArea

type TouchArea struct {
	Repository string        `json:"repository"`
	Selector   TouchSelector `json:"selector"`
	Intents    []string      `json:"intents"`
	Reason     string        `json:"reason,omitempty"`
}

type TouchSelector

type TouchSelector struct {
	Kind  string `json:"kind"`
	Value string `json:"value"`
}

type Validation

type Validation struct {
	Valid  bool    `json:"valid"`
	Issues []Issue `json:"issues"`
}

type Wave

type Wave struct {
	Identity
	Revisions       []WaveRevision `json:"-"`
	Heads           []string       `json:"-"`
	CurrentRevision *WaveRevision  `json:"-"`
}

type WaveRevision

type WaveRevision struct {
	Schema          string    `json:"$schema"`
	Version         int       `json:"version"`
	ID              string    `json:"id"`
	Wave            string    `json:"wave"`
	Parents         []string  `json:"parents"`
	Title           string    `json:"title"`
	Objective       string    `json:"objective"`
	Order           int       `json:"order"`
	EntryConditions []string  `json:"entry_conditions"`
	ExitConditions  []string  `json:"exit_conditions"`
	CreatedAt       time.Time `json:"created_at"`
	RequestID       string    `json:"request_id,omitempty"`
	RequestDigest   string    `json:"request_digest,omitempty"`
}

type WorkItem

type WorkItem struct {
	Identity
	Revisions       []WorkItemRevision `json:"-"`
	Heads           []string           `json:"-"`
	Progress        []ProgressEvent    `json:"-"`
	Workspaces      []WorkspaceEvent   `json:"-"`
	Merges          []MergeEvent       `json:"-"`
	CurrentRevision *WorkItemRevision  `json:"-"`
	CurrentProgress *ProgressEvent     `json:"-"`
}

type WorkItemRevision

type WorkItemRevision struct {
	Schema             string      `json:"$schema"`
	Version            int         `json:"version"`
	ID                 string      `json:"id"`
	WorkItem           string      `json:"work_item"`
	Parents            []string    `json:"parents"`
	Title              string      `json:"title"`
	Objective          string      `json:"objective"`
	Deliverables       []string    `json:"deliverables"`
	Wave               string      `json:"wave,omitempty"`
	Relations          []string    `json:"relations"`
	Dependencies       []string    `json:"dependencies"`
	Contracts          []string    `json:"contracts"`
	ExpectedTouchAreas []TouchArea `json:"expected_touch_areas"`
	CompletionChecks   []string    `json:"completion_checks"`
	MergeUnits         []MergeUnit `json:"merge_units"`
	CreatedAt          time.Time   `json:"created_at"`
	RequestID          string      `json:"request_id,omitempty"`
	RequestDigest      string      `json:"request_digest,omitempty"`
}

type Workspace

type Workspace struct {
	Provider     string `json:"provider"`
	ID           string `json:"id"`
	RepositoryID string `json:"repository_id"`
	Branch       string `json:"branch"`
	SourceBranch string `json:"source_branch,omitempty"`
	Label        string `json:"label,omitempty"`
}

type WorkspaceEvent

type WorkspaceEvent struct {
	EventBase
	WorkItem  string    `json:"work_item"`
	Action    string    `json:"action"`
	Role      string    `json:"role"`
	Workspace Workspace `json:"workspace"`
}

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL