constitution

package
v0.9.0 Latest Latest
Warning

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

 Go to latest Published: Jun 8, 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.