Help us shape the future of Go! Take the 2026 Go Developer Survey

constitution

package
v0.18.0 Latest Latest
Warning

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

 Go to latest Published: Sep 26, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Overview

Package constitution defines the hierarchical constitution system for VisionSpec. Constitutions define organizational defaults that flow down: org → team → project.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func IsZero 

func IsZero(v interface{}) bool

IsZero returns true if the value is the zero value for its type.

func ValidateInheritance 

func ValidateInheritance(child *Constitution, availableParents map[string]*Constitution) error

ValidateInheritance validates that a child constitution's inherits field references a valid parent.

Types

type APIs 

type APIs struct {
	REST RESTConfig `json:"rest,omitempty" yaml:"rest,omitempty"`
	GRPC GRPCConfig `json:"grpc,omitempty" yaml:"grpc,omitempty"`
}

APIs defines API style and framework choices.

type AuthConfig 

type AuthConfig struct {
	Provider string   `json:"provider,omitempty" yaml:"provider,omitempty"` // e.g., "oidc", "saml"
	MFA      string   `json:"mfa,omitempty" yaml:"mfa,omitempty"`           // e.g., "required", "optional"
	Methods  []string `json:"methods,omitempty" yaml:"methods,omitempty"`   // e.g., ["jwt", "api-key"]
}

AuthConfig defines authentication configuration.

type Availability 

type Availability struct {
	Target      AvailabilityTarget `json:"target" yaml:"target"`
	RTO         string             `json:"rto,omitempty" yaml:"rto,omitempty"` // e.g., "1h", "15m"
	RPO         string             `json:"rpo,omitempty" yaml:"rpo,omitempty"` // e.g., "15m", "1h"
	MultiRegion bool               `json:"multiRegion,omitempty" yaml:"multiRegion,omitempty"`
	MultiAZ     bool               `json:"multiAZ,omitempty" yaml:"multiAZ,omitempty"`
	DRStrategy  string             `json:"drStrategy,omitempty" yaml:"drStrategy,omitempty"` // e.g., "active-passive", "active-active"
}

Availability defines availability and reliability targets.

type AvailabilityTarget 

type AvailabilityTarget string

AvailabilityTarget represents SLA availability percentages. 

const (
	Availability99    AvailabilityTarget = "99"     // 99% - 3.65 days/year downtime
	Availability999   AvailabilityTarget = "99.9"   // 99.9% - 8.76 hours/year downtime
	Availability9999  AvailabilityTarget = "99.99"  // 99.99% - 52.6 minutes/year downtime
	Availability99999 AvailabilityTarget = "99.999" // 99.999% - 5.26 minutes/year downtime
)

func ValidAvailabilityTargets 

func ValidAvailabilityTargets() []AvailabilityTarget

ValidAvailabilityTargets returns all valid availability targets.

func (AvailabilityTarget) DowntimePerYear 

func (a AvailabilityTarget) DowntimePerYear() string

DowntimePerYear returns the approximate downtime per year for the target.

type Cloud 

type Cloud struct {
	Provider string   `json:"provider,omitempty" yaml:"provider,omitempty"` // e.g., "aws", "gcp", "azure"
	Regions  []string `json:"regions,omitempty" yaml:"regions,omitempty"`
}

Cloud defines cloud provider configuration.

type Constitution 

type Constitution struct {
	APIVersion     string         `json:"apiVersion" yaml:"apiVersion"` // visionspec/v1
	Kind           string         `json:"kind" yaml:"kind"`             // Constitution
	Metadata       Metadata       `json:"metadata" yaml:"metadata"`
	Technical      Technical      `json:"technical,omitempty" yaml:"technical,omitempty"`
	Infrastructure Infrastructure `json:"infrastructure,omitempty" yaml:"infrastructure,omitempty"`
	Security       Security       `json:"security,omitempty" yaml:"security,omitempty"`
	Prompts        Prompts        `json:"prompts,omitempty" yaml:"prompts,omitempty"`
}

Constitution represents a configuration document that defines defaults for VisionSpec artifacts at a given hierarchy level.

func Merge 

func Merge(parent, child *Constitution) *Constitution

Merge merges a child constitution into a parent, with child values taking precedence. Zero values in child are ignored (parent value preserved). This implements the inheritance model: org → team → project.

func Resolve 

func Resolve(constitutions ...*Constitution) (*Constitution, error)

Resolve resolves a constitution chain, applying inheritance from root to leaf. constitutions should be ordered from root (org) to leaf (project).

type Database 

type Database struct {
	Relational   string `json:"relational,omitempty" yaml:"relational,omitempty"`     // e.g., "postgresql"
	Document     string `json:"document,omitempty" yaml:"document,omitempty"`         // e.g., "mongodb"
	Cache        string `json:"cache,omitempty" yaml:"cache,omitempty"`               // e.g., "redis"
	Search       string `json:"search,omitempty" yaml:"search,omitempty"`             // e.g., "elasticsearch"
	MultiTenancy string `json:"multiTenancy,omitempty" yaml:"multiTenancy,omitempty"` // e.g., "rls", "schema", "database"
}

Database defines database choices.

type EncryptionConfig 

type EncryptionConfig struct {
	AtRest    string `json:"atRest,omitempty" yaml:"atRest,omitempty"`       // e.g., "aes-256"
	InTransit string `json:"inTransit,omitempty" yaml:"inTransit,omitempty"` // e.g., "tls-1.3"
}

EncryptionConfig defines encryption requirements.

type GRPCConfig 

type GRPCConfig struct {
	Framework string `json:"framework,omitempty" yaml:"framework,omitempty"` // e.g., "connect-go"
}

GRPCConfig defines gRPC configuration.

type IaC 

type IaC struct {
	Tool     IaCTool `json:"tool" yaml:"tool"`
	Language string  `json:"language,omitempty" yaml:"language,omitempty"` // e.g., "go", "typescript"
	RepoPath string  `json:"repoPath,omitempty" yaml:"repoPath,omitempty"` // e.g., "infra/"
}

IaC defines Infrastructure as Code choices.

type IaCTool 

type IaCTool string

IaCTool represents the IaC tool choice. 

const (
	IaCPulumi         IaCTool = "pulumi"
	IaCCDK            IaCTool = "cdk"
	IaCTerraform      IaCTool = "terraform"
	IaCCloudFormation IaCTool = "cloudformation"
	IaCNone           IaCTool = "none"
)

func ValidIaCTools 

func ValidIaCTools() []IaCTool

ValidIaCTools returns all valid IaC tools.

type InfraObservability 

type InfraObservability struct {
	Metrics ObservabilityPillar `json:"metrics,omitempty" yaml:"metrics,omitempty"`
	Traces  ObservabilityPillar `json:"traces,omitempty" yaml:"traces,omitempty"`
	Logging ObservabilityPillar `json:"logging,omitempty" yaml:"logging,omitempty"`
}

InfraObservability defines observability infrastructure (IRD scope).

type Infrastructure 

type Infrastructure struct {
	IaC           IaC                `json:"iac,omitempty" yaml:"iac,omitempty"`
	Observability InfraObservability `json:"observability,omitempty" yaml:"observability,omitempty"`
	LocalDev      LocalDev           `json:"localDev,omitempty" yaml:"localDev,omitempty"`
	Cloud         Cloud              `json:"cloud,omitempty" yaml:"cloud,omitempty"`
	Availability  Availability       `json:"availability,omitempty" yaml:"availability,omitempty"`
}

Infrastructure defines IRD-scoped defaults.

type LanguageChoice 

type LanguageChoice struct {
	Primary           string   `json:"primary" yaml:"primary"`                                         // e.g., "go"
	Allowed           []string `json:"allowed,omitempty" yaml:"allowed,omitempty"`                     // e.g., ["go", "rust"]
	ExceptionsRequire string   `json:"exceptionsRequire,omitempty" yaml:"exceptionsRequire,omitempty"` // e.g., "approval"
}

LanguageChoice defines a language selection with allowed alternatives.

type Languages 

type Languages struct {
	Backend  LanguageChoice `json:"backend,omitempty" yaml:"backend,omitempty"`
	Frontend LanguageChoice `json:"frontend,omitempty" yaml:"frontend,omitempty"`
	WASM     string         `json:"wasm,omitempty" yaml:"wasm,omitempty"` // e.g., "rust"
}

Languages defines programming language choices.

type Level 

type Level string

Level represents the hierarchy level of a constitution. 

const (
	LevelOrganization Level = "organization"
	LevelTeam         Level = "team"
	LevelProject      Level = "project"
)

type Loader 

type Loader interface {
	// Load returns the constitution for a given name.
	// Names follow the pattern: "org/<name>", "team/<name>", "project/<name>"
	Load(name string) (*Constitution, error)

	// LoadByLevel returns all constitutions at a given level.
	LoadByLevel(level Level) ([]*Constitution, error)

	// Available returns all available constitution names.
	Available() []string
}

Loader loads constitutions from various sources.

func NewChainLoader 

func NewChainLoader(loaders ...Loader) Loader

NewChainLoader creates a loader that tries multiple loaders in order. The first loader that can load a constitution wins. This is useful for organization-specific overrides: 

loader := constitution.NewChainLoader(
	orgLoader,        // Try org-specific first
	defaultLoader,    // Fall back to visionspec defaults
)

func NewEmbeddedLoader 

func NewEmbeddedLoader(fsys embed.FS, dir string) Loader

NewEmbeddedLoader creates a loader from embedded filesystem. Constitutions should be organized as: {dir}/org/*.yaml, {dir}/team/*.yaml, {dir}/project/*.yaml

Usage: 

//go:embed constitutions/**/*.yaml
var orgConstitutions embed.FS

loader := constitution.NewEmbeddedLoader(orgConstitutions, "constitutions")

func NewFileLoader 

func NewFileLoader(dir string) Loader

NewFileLoader creates a loader that reads constitutions from a directory. Constitutions should be organized as: {dir}/org/*.yaml, {dir}/team/*.yaml, {dir}/project/*.yaml

func NewMemoryLoader 

func NewMemoryLoader(constitutions ...*Constitution) Loader

NewMemoryLoader creates a loader from in-memory constitutions.

type LocalDev 

type LocalDev struct {
	Priority []LocalDevTarget `json:"priority,omitempty" yaml:"priority,omitempty"`
}

LocalDev defines local development environment preferences.

type LocalDevTarget 

type LocalDevTarget string

LocalDevTarget represents a local development target. 

const (
	LocalDevBinaries   LocalDevTarget = "binaries"
	LocalDevPodman     LocalDevTarget = "podman"
	LocalDevDocker     LocalDevTarget = "docker"
	LocalDevLocalStack LocalDevTarget = "localstack"
	LocalDevMinikube   LocalDevTarget = "minikube"
	LocalDevKind       LocalDevTarget = "kind"
)

func ValidLocalDevTargets 

func ValidLocalDevTargets() []LocalDevTarget

ValidLocalDevTargets returns all valid local dev targets.

type Metadata 

type Metadata struct {
	Name        string    `json:"name" yaml:"name"`
	Level       Level     `json:"level" yaml:"level"`
	Inherits    string    `json:"inherits,omitempty" yaml:"inherits,omitempty"` // e.g., "org/plexusone"
	Version     string    `json:"version,omitempty" yaml:"version,omitempty"`
	Description string    `json:"description,omitempty" yaml:"description,omitempty"`
	UpdatedAt   time.Time `json:"updatedAt,omitempty" yaml:"updatedAt,omitempty"`
}

Metadata contains constitution identification and hierarchy info.

type ObservabilityPillar 

type ObservabilityPillar struct {
	Platform      string `json:"platform,omitempty" yaml:"platform,omitempty"`           // e.g., "prometheus", "loki"
	Visualization string `json:"visualization,omitempty" yaml:"visualization,omitempty"` // e.g., "grafana"
	Backend       string `json:"backend,omitempty" yaml:"backend,omitempty"`             // e.g., "langfuse" (for traces)
	Collector     string `json:"collector,omitempty" yaml:"collector,omitempty"`         // e.g., "opentelemetry-collector"
}

ObservabilityPillar defines a single observability pillar configuration.

type Prompts 

type Prompts struct {
	LanguageChoice     string `json:"languageChoice,omitempty" yaml:"languageChoice,omitempty"`
	APIDesign          string `json:"apiDesign,omitempty" yaml:"apiDesign,omitempty"`
	DatabaseChoice     string `json:"databaseChoice,omitempty" yaml:"databaseChoice,omitempty"`
	TenancyChoice      string `json:"tenancyChoice,omitempty" yaml:"tenancyChoice,omitempty"`
	AvailabilityChoice string `json:"availabilityChoice,omitempty" yaml:"availabilityChoice,omitempty"`
}

Prompts contains LLM guidance prompts for decision-making.

type RESTConfig 

type RESTConfig struct {
	Framework  string `json:"framework,omitempty" yaml:"framework,omitempty"`   // e.g., "huma-chi"
	SpecFormat string `json:"specFormat,omitempty" yaml:"specFormat,omitempty"` // e.g., "openapi-3.1"
	StyleGuide string `json:"styleGuide,omitempty" yaml:"styleGuide,omitempty"` // e.g., "google-api-design-guide"
}

RESTConfig defines REST API configuration.

type Resolver 

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

Resolver resolves constitution chains with inheritance.

func NewResolver 

func NewResolver(loader Loader) *Resolver

NewResolver creates a constitution resolver.

func (*Resolver) ResolveChain 

func (r *Resolver) ResolveChain(name string) (*Constitution, error)

ResolveChain resolves a constitution by loading and merging its inheritance chain. Given "project/myproject", it loads:

  • The project constitution
  • Its inherited team constitution (if any)
  • The team's inherited org constitution (if any)

Then merges them in order: org → team → project

type SecretsConfig 

type SecretsConfig struct {
	Provider string `json:"provider,omitempty" yaml:"provider,omitempty"` // e.g., "aws-secrets-manager", "vault"
}

SecretsConfig defines secrets management.

type Security 

type Security struct {
	Secrets    SecretsConfig    `json:"secrets,omitempty" yaml:"secrets,omitempty"`
	Encryption EncryptionConfig `json:"encryption,omitempty" yaml:"encryption,omitempty"`
	Auth       AuthConfig       `json:"auth,omitempty" yaml:"auth,omitempty"`
}

Security defines security configuration.

type TechObservability 

type TechObservability struct {
	Library        string `json:"library,omitempty" yaml:"library,omitempty"` // e.g., "github.com/plexusone/omniobserve"
	AutoInstrument bool   `json:"autoInstrument,omitempty" yaml:"autoInstrument,omitempty"`
	MetricsSDK     string `json:"metricsSDK,omitempty" yaml:"metricsSDK,omitempty"` // e.g., "prometheus/client_golang"
	TracesSDK      string `json:"tracesSDK,omitempty" yaml:"tracesSDK,omitempty"`   // e.g., "opentelemetry-go"
	LoggingSDK     string `json:"loggingSDK,omitempty" yaml:"loggingSDK,omitempty"` // e.g., "slog"
}

TechObservability defines instrumentation choices (TRD scope).

type Technical 

type Technical struct {
	Languages     Languages         `json:"languages,omitempty" yaml:"languages,omitempty"`
	APIs          APIs              `json:"apis,omitempty" yaml:"apis,omitempty"`
	Database      Database          `json:"database,omitempty" yaml:"database,omitempty"`
	Tenancy       Tenancy           `json:"tenancy,omitempty" yaml:"tenancy,omitempty"`
	Observability TechObservability `json:"observability,omitempty" yaml:"observability,omitempty"`
}

Technical defines TRD-scoped defaults.

type Tenancy 

type Tenancy struct {
	Model          TenancyModel `json:"model" yaml:"model"`
	Isolation      string       `json:"isolation,omitempty" yaml:"isolation,omitempty"`           // e.g., "rls", "schema", "database"
	TenantIDHeader string       `json:"tenantIdHeader,omitempty" yaml:"tenantIdHeader,omitempty"` // e.g., "X-Tenant-ID"
	TenantIDClaim  string       `json:"tenantIdClaim,omitempty" yaml:"tenantIdClaim,omitempty"`   // e.g., "tenant_id" (JWT claim)
}

Tenancy defines multi-tenancy configuration.

type TenancyModel 

type TenancyModel string

TenancyModel represents the tenancy architecture. 

const (
	TenancySingleTenant TenancyModel = "single-tenant"
	TenancyMultiTenant  TenancyModel = "multi-tenant"
)

func ValidTenancyModels 

func ValidTenancyModels() []TenancyModel

ValidTenancyModels returns all valid tenancy models.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.