lockfile

Documentation

Overview

Package lockfile reads and writes txco.packages.lock.yaml — the repo-root, committed record of which packages produced the workspace's materialized files (workspace PROVENANCE). It is deliberately separate from the chassis's server-side manifest_hash / version lineage (runtime truth); see docs/txco-oci-packages.md §7.

The lockfile is tool-owned (no user comments), so a yaml.Marshal round-trip is safe here — unlike txco.yaml, which install never rewrites.

Index

• Constants
• func Now() string
• func Path(root string) string
• func Write(root string, f *File) error
• type Entry
• type File
  • func Read(root string) (*File, error)
  • func (f *File) FindStack(stack string) *Entry
  • func (f *File) Remove(stack string) bool
  • func (f *File) Upsert(e Entry)

Constants

const FileName = "txco.packages.lock.yaml"

FileName is the lockfile name; it lives at the workspace root and is committed.

Functions

func Now

func Now() string

Now returns the current install timestamp (RFC3339 UTC).

func Path

func Path(root string) string

Path returns the lockfile path for a workspace root.

func Write

func Write(root string, f *File) error

Write serializes the lockfile to root, sorted for stable git diffs.

Types

type Entry

type Entry struct {
	Ref           string `yaml:"ref"`                     // exactly what the user typed
	Registry      string `yaml:"registry,omitempty"`      // provenance
	Namespace     string `yaml:"namespace,omitempty"`     // provenance
	Name          string `yaml:"name"`                    // manifest identity
	Version       string `yaml:"version"`                 // manifest identity
	Resolved      string `yaml:"resolved,omitempty"`      // oci://…@sha256 (Phase 2)
	ExportedStack string `yaml:"exportedStack,omitempty"` // stack the package ships
	InstalledAs   string `yaml:"installedAs,omitempty"`   // where it was materialized
	Mode          string `yaml:"mode"`                    // as-stack | vendor-only
	ManifestHash  string `yaml:"manifestHash,omitempty"`  // localManifestHash of materialized files
	SignedBy      string `yaml:"signedBy,omitempty"`      // trusted signer key id, when verified (Phase 5)
	InstalledAt   string `yaml:"installedAt"`
}

Entry records one installed package. registry/namespace/resolved are PROVENANCE from the resolved ref (blank for dir:/file: sources in Phase 1, filled when OCI lands); name/version are the package's own identity.

type File

type File struct {
	Packages []Entry `yaml:"packages"`
}

func Read

func Read(root string) (*File, error)

Read loads the lockfile at root. A missing file yields an empty File (nil error).

func (*File) FindStack

func (f *File) FindStack(stack string) *Entry

FindStack returns the entry that installed the given stack, or nil. Used to decide whether install owns a stack dir (safe to overwrite) vs. would clobber untracked content.

func (*File) Remove

func (f *File) Remove(stack string) bool

Remove deletes the as-stack entry installed as `stack`, re-sorts, and reports whether an entry was removed. Symmetric with FindStack: vendor-only entries (no InstalledAs) are never matched. Used by `txco package remove`.

func (*File) Upsert

func (f *File) Upsert(e Entry)

Upsert replaces any entry occupying the same slot, else appends.