format

Documentation

Overview

Package format owns FXVCS format-version negotiation: the committed document envelope (apiVersion/kind), semantic version comparison for minimumFXVCSVersion, pointer/object format identifiers, Git integration generations, and local SQLite schema versions.

The rules are normative (docs/spec/version-negotiation.md):

• Every persisted document starts with a format version.
• Readers accept documented older versions and reject unknown or newer versions before performing any write.
• A repository whose minimumFXVCSVersion exceeds the running binary refuses every normal operation; only the compatibility diagnostic may run.

Index

• Constants
• Variables
• func CheckGitIntegrationGeneration(required int, repository string, installed Version) error
• func CheckMinimumVersion(installed Version, minimum string, repository string) error
• func ParseAPIVersion(apiVersion string) (group, version string, err error)
• func ValidateEnvelope(env Envelope, expectKind string) error
• type Envelope
• type UpgradeRequiredError
  • func (e *UpgradeRequiredError) Error() string
• type Version
  • func MustParseVersion(s string) Version
  • func ParseVersion(s string) (Version, error)
  • func (v Version) Compare(o Version) int
  • func (v Version) String() string

Constants

const (
	PointerFormatVersion       = 1 // internal/pointer
	ObjectManifestVersion      = 1 // canonical JSON object manifest
	AssetIndexVersion          = 1 // canonical JSON asset index
	GitIntegrationGeneration   = 1 // filter+diff+merge+-text
	HydrationStateSchema       = 2 // $GIT_DIR/fxvcs/state.db
	PublicationLedgerSchema    = 1 // $GIT_COMMON_DIR/fxvcs/publication.db
	AgentStateSchema           = 1 // agent observed-state database
	TemplateRendererVersion    = "template.v1"
	SDKMajor                   = 0
	FilterProtocolVersion      = 2 // Git long-running filter protocol version
	SDKAPIVersion              = "fxvcs.dev/sdk/v0"
	MaximumSupportedIntegrator = GitIntegrationGeneration
)

Format identifiers that version themselves independently of apiVersion.

const (
	KindRepository             = "Repository"
	KindResourceCatalog        = "ResourceCatalog"
	KindRuntimeResourceCatalog = "RuntimeResourceCatalog"
	KindResourceOverrides      = "ResourceOverrides"
	KindStack                  = "Stack"
	KindRelease                = "Release"
	KindEnvironment            = "Environment"
	KindTarget                 = "Target"
	KindLocalConfig            = "LocalConfig"
	KindAgentConfig            = "AgentConfig"
)

Kinds of committed documents.

const CurrentAPIVersion = Group + "/v1alpha1"

CurrentAPIVersion is the committed-document schema version this binary writes.

const Group = "fxvcs.dev"

Group is the API group for every committed FXVCS document.

Variables

var (
	ErrUnknownAPIVersion   = errors.New("format: unknown apiVersion")
	ErrNewerAPIVersion     = errors.New("format: document apiVersion is newer than this binary supports")
	ErrUnknownKind         = errors.New("format: unknown kind")
	ErrInvalidSemver       = errors.New("format: invalid semantic version")
	ErrUnsupportedGen      = errors.New("format: unsupported Git integration generation")
	ErrUnsupportedPointer  = errors.New("format: unsupported pointer format version")
	ErrUnsupportedSchemaDB = errors.New("format: unsupported local database schema version")
)

Errors returned by negotiation. Callers must check with errors.Is / errors.As and must not write anything after receiving them.

var KnownKinds = map[string]bool{
	KindRepository: true, KindResourceCatalog: true, KindRuntimeResourceCatalog: true,
	KindResourceOverrides: true, KindStack: true, KindRelease: true,
	KindEnvironment: true, KindTarget: true, KindLocalConfig: true, KindAgentConfig: true,
}

KnownKinds is the closed set of committed/local document kinds.

var SupportedAPIVersions = []string{CurrentAPIVersion}

SupportedAPIVersions lists every committed-document version this binary can read, oldest first. Currently exactly one; upgrades append here and add an ordered migration in internal/migrate.

Functions

func CheckGitIntegrationGeneration

func CheckGitIntegrationGeneration(required int, repository string, installed Version) error

CheckGitIntegrationGeneration gates filter/diff/merge entry points.

func CheckMinimumVersion

func CheckMinimumVersion(installed Version, minimum string, repository string) error

CheckMinimumVersion implements the client gate. installed is the running binary; minimum is the repository/coordination declaration ("" means none). A non-nil error is always *UpgradeRequiredError (or ErrInvalidSemver).

func ParseAPIVersion

func ParseAPIVersion(apiVersion string) (group, version string, err error)

ParseAPIVersion splits "fxvcs.dev/v1alpha1" into group and version and classifies it as supported, newer, or unknown. A version is "newer" when it has the correct group and a lexically/numerically later version token than any supported version, so that a downgraded binary reports the right error.

func ValidateEnvelope

func ValidateEnvelope(env Envelope, expectKind string) error

ValidateEnvelope checks the apiVersion and kind of a committed document. It returns nil only when the document may proceed to schema validation.

Types

type Envelope

type Envelope struct {
	APIVersion string `json:"apiVersion" yaml:"apiVersion"`
	Kind       string `json:"kind" yaml:"kind"`
}

Envelope is the leading portion of every committed document.

type UpgradeRequiredError

type UpgradeRequiredError struct {
	Installed  Version
	Required   Version
	Repository string // repository path or coordination record, for diagnostics
	Reason     string // e.g. "minimumFXVCSVersion", "gitIntegrationVersion"
}

UpgradeRequiredError is the only result a below-minimum client may report. It carries the installed and required versions so CLI, filter, agent, and desktop can print an actionable message. It is deliberately not wrapped in other operation results: a client that receives it must stop.

func (*UpgradeRequiredError) Error

func (e *UpgradeRequiredError) Error() string

type Version

type Version struct {
	Major, Minor, Patch int
	Pre                 string
}

Version is a semantic version without build metadata; prerelease is compared per SemVer 2.0 §11.

func MustParseVersion

func MustParseVersion(s string) Version

MustParseVersion panics on invalid input; for compile-time constants only.

func ParseVersion

func ParseVersion(s string) (Version, error)

ParseVersion parses "1.2.3", "v1.2.3", "1.2.3-rc.1", ignoring build metadata.

func (Version) Compare

func (v Version) Compare(o Version) int

Compare returns -1, 0, or 1.

func (Version) String

func (v Version) String() string