environment

package
v0.14.4-dev.19 Latest Latest
Warning

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

Go to latest
Published: Nov 21, 2026 License: MIT Imports: 25 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source
var ErrNoReceipt = errors.New("no successful current-format probe receipt; run probe")

ErrNoReceipt reports that "latest" was requested where no successful probe has been saved.

Functions

func ClearBinding

func ClearBinding(workspaceRoot string) error

ClearBinding removes the association for a workspace.

func Dir

func Dir(name string) (string, error)

Dir returns the directory for a named environment under AGENTPACK_HOME.

func ExecutableIdentity

func ExecutableIdentity(path string) (string, error)

ExecutableIdentity hashes native bytes without running the executable.

func ExportBundle

func ExportBundle(definitionRoot, destination string) error

ExportBundle preserves definition bytes and refuses inputs that cannot safely travel.

func ExternalCapability

func ExternalCapability(target base.Target) (status, note string)

ExternalCapability describes whether an adapter can run without checkout writes.

func ImportBundle

func ImportBundle(bundlePath, destination string) (string, error)

ImportBundle validates privately before atomically publishing a new directory.

func Init

func Init(name, destination, fromProject string) (string, error)

Init publishes a complete local definition; copied path dependencies retain their original source.

func List

func List() ([]string, error)

List returns named environments under AGENTPACK_HOME/environments.

func ReceiptsRoot

func ReceiptsRoot(workspaceRoot string) (string, error)

ReceiptsRoot is $AGENTPACK_HOME/projects/<hash>/probe-receipts.

func RedactDiagnosticExport added in v0.14.0

func RedactDiagnosticExport(value any) (any, error)

RedactDiagnosticExport applies the capsule's private-path policy to JSON-shaped diagnostics.

func ResolveRef

func ResolveRef(ref string) (string, error)

ResolveRef turns a name or filesystem path into an absolute definition root.

func Root

func Root() (string, error)

Root returns $AGENTPACK_HOME/environments.

func SaveBinding

func SaveBinding(binding Binding) error

SaveBinding writes the workspace → definition association.

func SaveReceipt

func SaveReceipt(workspaceRoot string, receipt Receipt) (string, error)

SaveReceipt writes a receipt JSON file and returns its path.

func ValidateContract

func ValidateContract(contract Contract) error

ValidateContract rejects unknown schema majors and invalid requirement shapes.

func ValidateReceipt

func ValidateReceipt(receipt Receipt) error

ValidateReceipt checks record shape; unsuccessful records remain loadable for diagnostics.

func WriteSupportCapsule

func WriteSupportCapsule(destination string, capsule SupportCapsule) error

WriteSupportCapsule writes the capsule JSON to destination.

Types

type Allowance

type Allowance struct {
	RequirementID string `json:"requirement_id"`
	Rationale     string `json:"rationale"`
}

Allowance scopes an exception with a rationale (no blanket ignore-all).

type ArtifactRecord

type ArtifactRecord struct {
	Properties map[string]any `json:"properties,omitempty"`
	OutputPath string         `json:"output_path,omitempty"`
	ID         string         `json:"id"`
	Kind       string         `json:"kind"`
	Name       string         `json:"name"`
	Module     string         `json:"module,omitempty"`
	Winner     string         `json:"winner,omitempty"` // package | user | project | plugin
	Omitted    bool           `json:"omitted,omitempty"`
	Reason     string         `json:"reason,omitempty"`
	Evidence   EvidenceLevel  `json:"evidence,omitempty"`
}

ArtifactRecord is a planned package artifact identity for effective-plan reports.

type Binding

type Binding struct {
	Environment    string `toml:"environment"`
	DefinitionRoot string `toml:"definition_root"`
	WorkspaceRoot  string `toml:"workspace_root"`
}

Binding associates a workspace checkout with an external definition root.

func LoadBinding

func LoadBinding(workspaceRoot string) (Binding, bool, error)

LoadBinding returns the binding for a workspace, if any.

type Comparison

type Comparison struct {
	Compatible bool     `json:"compatible"`
	LeftID     string   `json:"left_id"`
	RightID    string   `json:"right_id"`
	Deltas     []string `json:"deltas"`
	Unknowns   []string `json:"unknowns,omitempty"`
}

Comparison is a structured delta between two receipts.

func CompareReceipts

func CompareReceipts(left, right Receipt) Comparison

CompareReceipts diffs compatible receipt categories. Unobserved fields stay unknown.

type Contract

type Contract struct {
	SchemaVersion   int           `json:"schema_version"`
	Requirements    []Requirement `json:"requirements"`
	Allowances      []Allowance   `json:"allowances"`
	UnknownRequired string        `json:"unknown_required"` // fail | warn | allow
}

Contract is a versioned requirement set attached to an external definition.

func LoadContract

func LoadContract(path string) (Contract, error)

LoadContract reads a JSON contract file.

type ContractResult

type ContractResult struct {
	RequirementID string `json:"requirement_id"`
	Result        string `json:"result"` // satisfied | violated | unknown | not_applicable
	FindingCode   string `json:"finding_code,omitempty"`
	Message       string `json:"message,omitempty"`
}

ContractResult is one requirement outcome.

func EvaluateContract

func EvaluateContract(contract Contract, report Report) []ContractResult

EvaluateContract scores requirements against a preflight report. Observed-only predicates that lack receipts stay unknown (never forged from generated digests).

type CoverageNote

type CoverageNote struct {
	Category     string `json:"category"`
	Scope        string `json:"scope"`
	Completeness string `json:"completeness"` // complete | partial | none
	Reason       string `json:"reason,omitempty"`
}

CoverageNote records observation completeness for a category.

type EvidenceLevel

type EvidenceLevel string

EvidenceLevel grades how a property was established.

const (
	EvidenceDeclared  EvidenceLevel = "declared"
	EvidenceGenerated EvidenceLevel = "generated"
	EvidenceObserved  EvidenceLevel = "observed"
	EvidenceUnknown   EvidenceLevel = "unknown"
)

type Finding

type Finding struct {
	Code        string        `json:"code"`
	Severity    Severity      `json:"severity"`
	Source      string        `json:"source,omitempty"`
	Target      string        `json:"target,omitempty"`
	Winner      string        `json:"winner,omitempty"`
	Message     string        `json:"message"`
	Remedy      string        `json:"remedy,omitempty"`
	Consequence string        `json:"consequence,omitempty"`
	Remediation *Remediation  `json:"remediation,omitempty"`
	ArtifactID  string        `json:"artifact_id,omitempty"`
	Property    string        `json:"property,omitempty"`
	RelatedRefs []string      `json:"related_refs,omitempty"`
	Evidence    EvidenceLevel `json:"evidence,omitempty"`
	Accepted    bool          `json:"accepted,omitempty"`
}

Finding is a stable, actionable preflight record.

type ObservedProperty

type ObservedProperty struct {
	EvidenceDigest string        `json:"evidence_digest,omitempty"`
	Scope          string        `json:"scope,omitempty"`
	Category       string        `json:"category,omitempty"`
	ArtifactID     string        `json:"artifact_id,omitempty"`
	Property       string        `json:"property"`
	Value          any           `json:"value"`
	Evidence       EvidenceLevel `json:"evidence"`
	Method         string        `json:"method,omitempty"`
	EvidenceRef    string        `json:"evidence_ref,omitempty"`
	Reason         string        `json:"reason,omitempty"`
}

ObservedProperty is one graded native observation.

type Policy

type Policy string

Policy selects how inheritance and conversion findings are treated.

const (
	// PolicyLocal allows inherited user config (developer machines).
	PolicyLocal Policy = "local"
	// PolicyCI treats undeclared inheritance and conversion loss as violations.
	PolicyCI Policy = "ci"
)

func ParsePolicy

func ParsePolicy(value string) (Policy, error)

type ProbeEffects

type ProbeEffects struct {
	ModelCalls bool   `json:"model_calls"`
	Network    string `json:"network"`
	WriteScope string `json:"write_scope"`
}

ProbeEffects declares measured/configured side effects.

type Receipt

type Receipt struct {
	DiagnosticRefs  []string           `json:"diagnostic_refs,omitempty"`
	SchemaVersion   int                `json:"schema_version"`
	Phase           string             `json:"phase"`
	ReceiptID       string             `json:"receipt_id"`
	SourceIdentity  string             `json:"source_id,omitempty"`
	LockDigest      string             `json:"lock_digest,omitempty"`
	WorkspaceDigest string             `json:"workspace_digest,omitempty"`
	GenerationID    string             `json:"generation_id,omitempty"`
	Mode            string             `json:"mode,omitempty"`
	PolicyDigest    string             `json:"policy_digest,omitempty"`
	Target          ReceiptTarget      `json:"target"`
	CreatedAt       time.Time          `json:"created_at"`
	Coverage        []CoverageNote     `json:"coverage"`
	Properties      []ObservedProperty `json:"properties"`
	ContractResults []ContractResult   `json:"contract_results,omitempty"`
	Findings        []Finding          `json:"findings"`
	Effects         ProbeEffects       `json:"effects"`
	Termination     Termination        `json:"termination"`
	OverallStatus   string             `json:"overall_status"`
}

Receipt is a local native observation record (not a publisher attestation).

func LoadReceipt

func LoadReceipt(workspaceRoot, idOrPath string) (Receipt, error)

LoadReceipt loads a receipt by ID or absolute path.

func NormalizeReceipt added in v0.9.0

func NormalizeReceipt(receipt Receipt) Receipt

NormalizeReceipt applies the same compatibility mapping to persisted findings.

type ReceiptTarget

type ReceiptTarget struct {
	Adapter            string `json:"adapter"`
	AdapterRevision    string `json:"adapter_revision,omitempty"`
	ExecutableIdentity string `json:"executable_identity,omitempty"`
	NativeVersion      string `json:"native_version,omitempty"`
	CapabilityRevision string `json:"capability_revision,omitempty"`
}

ReceiptTarget identifies the native adapter under test.

type Remediation added in v0.9.0

type Remediation struct {
	Message string   `json:"message"`
	Argv    []string `json:"argv,omitempty"`
}

Remediation is a human instruction and, when a concrete safe command is known, its argument vector. Argv is never parsed from Remedy text.

type Report

type Report struct {
	SchemaVersion   int                `json:"schema_version"`
	Phase           string             `json:"phase"`
	Environment     string             `json:"environment,omitempty"`
	DefinitionRoot  string             `json:"definition_root"`
	WorkspaceRoot   string             `json:"workspace_root"`
	Mode            string             `json:"mode"`
	Target          string             `json:"target,omitempty"`
	Policy          Policy             `json:"policy"`
	StrictExternal  bool               `json:"strict_external"`
	WorkspaceDigest string             `json:"workspace_digest,omitempty"`
	GenerationID    string             `json:"generation_id,omitempty"`
	PolicyDigest    string             `json:"policy_digest,omitempty"`
	ExpectedTarget  ReceiptTarget      `json:"expected_target"`
	Properties      []ObservedProperty `json:"properties,omitempty"`
	SourceIdentity  string             `json:"source_identity,omitempty"`
	LockDigest      string             `json:"lock_digest,omitempty"`
	Skills          int                `json:"skills"`
	Plugins         int                `json:"plugins"`
	Shadowed        int                `json:"shadowed"`
	Inheritance     []string           `json:"inheritance,omitempty"`
	Capabilities    map[string]string  `json:"capabilities,omitempty"`
	PlannedWrites   []string           `json:"planned_writes,omitempty"`
	Artifacts       []ArtifactRecord   `json:"artifacts,omitempty"`
	Coverage        []CoverageNote     `json:"coverage,omitempty"`
	ContractResults []ContractResult   `json:"contract_results,omitempty"`
	Findings        []Finding          `json:"findings"`
	OverallStatus   string             `json:"overall_status"`
	OK              bool               `json:"ok"`
}

Report is the shared human/JSON preflight payload.

func NormalizeReport added in v0.9.0

func NormalizeReport(report Report) Report

NormalizeReport fills structured finding metadata that is known from the report, while retaining Remedy for existing consumers.

func (Report) HasObservedCoverage

func (report Report) HasObservedCoverage(category string) bool

HasObservedCoverage reports whether a category has complete observed coverage.

func (Report) HasObservedCoverageScope

func (report Report) HasObservedCoverageScope(category, scope string) bool

type Requirement

type Requirement struct {
	ID              string         `json:"id"`
	Target          string         `json:"target"`
	Selector        map[string]any `json:"selector"`
	Predicate       string         `json:"predicate"`
	Expected        any            `json:"expected,omitempty"`
	MinimumEvidence string         `json:"minimum_evidence"`
	Severity        Severity       `json:"severity"`
}

Requirement is one evaluable check. Predicates are closed; never evaluate pack-supplied expressions.

type Severity

type Severity string

Severity ranks a preflight finding for CI policy.

const (
	SeverityInfo      Severity = "info"
	SeverityWarning   Severity = "warning"
	SeverityError     Severity = "error"
	SeverityViolation Severity = "violation"
)

type SupportCapsule

type SupportCapsule struct {
	SchemaVersion int                `json:"schema_version"`
	ExportedAt    time.Time          `json:"exported_at"`
	Scope         string             `json:"scope"`
	ReceiptID     string             `json:"receipt_id"`
	Adapter       string             `json:"adapter,omitempty"`
	NativeVersion string             `json:"native_version,omitempty"`
	SourceID      string             `json:"source_id_prefix,omitempty"`
	LockDigest    string             `json:"lock_digest_prefix,omitempty"`
	Mode          string             `json:"mode,omitempty"`
	Coverage      []CoverageNote     `json:"coverage,omitempty"`
	Findings      []Finding          `json:"findings,omitempty"`
	Properties    []ObservedProperty `json:"properties,omitempty"`
	OverallStatus string             `json:"overall_status,omitempty"`
	Notes         []string           `json:"notes"`
}

SupportCapsule is a redacted, opt-in diagnostic export. It never includes credentials, raw environment values, or absolute private path contents.

func ExportSupportCapsule

func ExportSupportCapsule(receipt Receipt) SupportCapsule

ExportSupportCapsule builds a redacted capsule from a receipt.

type Termination

type Termination struct {
	Status         string `json:"status"`
	NativeExitCode int    `json:"native_exit_code"`
}

Termination records process outcome separately from policy status.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL