state

Documentation

Index

• Constants
• type Entry
• type State
  • func Load(dir string) (*State, error)
  • func (s *State) CatalogVersionRecorded() string
  • func (s *State) Delete(tool, key string)
  • func (s *State) Get(tool, key string) (Entry, bool)
  • func (s *State) HomontoVersionRecorded() string
  • func (s *State) Keys(tool string) []string
  • func (s *State) Save(dir string) error
  • func (s *State) Set(tool, key, desired, appliedHash string)
  • func (s *State) SetCatalogVersion(v string)
  • func (s *State) SetFrameworkVersion(name, version string)
  • func (s *State) SetHomontoVersion(v string)
  • func (s *State) SetSubagentRenderFingerprint(v string)
  • func (s *State) SubagentRenderFingerprintRecorded() string

Constants

const CurrentStateSchemaVersion = 1

CurrentStateSchemaVersion is the state.json schema version this binary writes.

Types

type Entry

type Entry struct {
	Desired string `json:"desired"`
	Applied string `json:"applied"`
}

Entry is the last-applied record for one managed key. Desired holds the unresolved value (may contain ${...} tokens); Applied holds a non-secret sha256 of the resolved value that was written to disk. Neither field ever contains a plaintext secret, so state.json is safe to share.

type State

type State struct {
	// SchemaVersion is the state.json format version. Absent/0 means a legacy
	// (pre-versioning) file and is treated as the current version; a value greater
	// than CurrentStateSchemaVersion is rejected fail-closed at load.
	SchemaVersion  int                         `json:"schemaVersion,omitempty"`
	Managed        map[string]map[string]Entry `json:"managed"`
	CatalogVersion string                      `json:"catalogVersion,omitempty"`
	// HomontoVersion is the homonto binary version that performed the last apply.
	// It lets `onto` detect a binary/framework version skew (its own version vs
	// the homonto that projected the framework) and lets `homonto update` report
	// the transition. Absent on legacy state files.
	HomontoVersion string `json:"homontoVersion,omitempty"`
	// FrameworkVersions records the version of each builtin framework at the last
	// apply (framework name -> version), so a version history is written down.
	FrameworkVersions map[string]string `json:"frameworkVersions,omitempty"`
	// SubagentRenderFingerprint digests the config-derived inputs behind the last
	// subagent materialization (the per-tool model routes). A subagent's rendered
	// frontmatter depends on config, not only on the catalog, so the catalog
	// version alone cannot gate materialization: editing a model route leaves the
	// version untouched and would otherwise freeze the rendered agents at their
	// old model forever. Absent = force re-render.
	SubagentRenderFingerprint string `json:"subagentRenderFingerprint,omitempty"`
}

State is the last-applied snapshot, keyed tool -> managed key -> Entry. CatalogVersion is the embedded-catalog version last successfully materialized; it is global (not per-tool) and omitted when empty so pre-catalog state.json files stay backward-compatible (absent = "force materialize").

func Load

func Load(dir string) (*State, error)

Load reads <dir>/state.json, returning an empty State if the file is absent.

func (*State) CatalogVersionRecorded

func (s *State) CatalogVersionRecorded() string

CatalogVersionRecorded returns the catalog version last materialized, or "".

func (*State) Delete

func (s *State) Delete(tool, key string)

Delete drops the record for a key (after its on-disk value was pruned).

func (*State) Get

func (s *State) Get(tool, key string) (Entry, bool)

Get returns the recorded Entry for a key and whether it exists.

func (*State) HomontoVersionRecorded

func (s *State) HomontoVersionRecorded() string

HomontoVersionRecorded returns the homonto binary version that last applied, or "" for a legacy/never-applied state.

func (*State) Keys

func (s *State) Keys(tool string) []string

Keys returns the sorted managed keys recorded for a tool.

func (*State) Save

func (s *State) Save(dir string) error

Save writes the state atomically (temp + fsync + rename), creating dir if needed. state.json is one of homonto's own control-plane files, so it is written no-follow (a symlinked target is refused, never followed) at 0600.

func (*State) Set

func (s *State) Set(tool, key, desired, appliedHash string)

Set records the unresolved desired value and the applied-value hash for a key.

func (*State) SetCatalogVersion

func (s *State) SetCatalogVersion(v string)

SetCatalogVersion records the catalog version after a successful materialize.

func (*State) SetFrameworkVersion

func (s *State) SetFrameworkVersion(name, version string)

SetFrameworkVersion records one framework's version at apply time.

func (*State) SetHomontoVersion

func (s *State) SetHomontoVersion(v string)

SetHomontoVersion records the homonto binary version at apply time. An empty value (unstamped/dev build) is ignored so a dev run never overwrites a real recorded version with a placeholder.

func (*State) SetSubagentRenderFingerprint

func (s *State) SetSubagentRenderFingerprint(v string)

SetSubagentRenderFingerprint records the render fingerprint after a successful subagent materialize.

func (*State) SubagentRenderFingerprintRecorded

func (s *State) SubagentRenderFingerprintRecorded() string

SubagentRenderFingerprintRecorded returns the render fingerprint behind the last subagent materialization, or "" (never materialized / legacy state).