Documentation
¶
Index ¶
- Variables
- func ClearBinding(workspaceRoot string) error
- func Dir(name string) (string, error)
- func ExecutableIdentity(path string) (string, error)
- func ExportBundle(definitionRoot, destination string) error
- func ExternalCapability(target base.Target) (status, note string)
- func ImportBundle(bundlePath, destination string) (string, error)
- func Init(name, destination, fromProject string) (string, error)
- func List() ([]string, error)
- func ReceiptsRoot(workspaceRoot string) (string, error)
- func ResolveRef(ref string) (string, error)
- func Root() (string, error)
- func SaveBinding(binding Binding) error
- func SaveReceipt(workspaceRoot string, receipt Receipt) (string, error)
- func ValidateContract(contract Contract) error
- func ValidateReceipt(receipt Receipt) error
- func WriteSupportCapsule(destination string, capsule SupportCapsule) error
- type Allowance
- type ArtifactRecord
- type Binding
- type Comparison
- type Contract
- type ContractResult
- type CoverageNote
- type EvidenceLevel
- type Finding
- type ObservedProperty
- type Policy
- type ProbeEffects
- type Receipt
- type ReceiptTarget
- type Report
- type Requirement
- type Severity
- type SupportCapsule
- type Termination
Constants ¶
This section is empty.
Variables ¶
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 ¶
ClearBinding removes the association for a workspace.
func ExecutableIdentity ¶
ExecutableIdentity hashes native bytes without running the executable.
func ExportBundle ¶
ExportBundle preserves definition bytes and refuses inputs that cannot safely travel.
func ExternalCapability ¶
ExternalCapability describes whether an adapter can run without checkout writes.
func ImportBundle ¶
ImportBundle validates privately before atomically publishing a new directory.
func Init ¶
Init publishes a complete local definition; copied path dependencies retain their original source.
func ReceiptsRoot ¶
ReceiptsRoot is $AGENTPACK_HOME/projects/<hash>/probe-receipts.
func ResolveRef ¶
ResolveRef turns a name or filesystem path into an absolute definition root.
func SaveBinding ¶
SaveBinding writes the workspace → definition association.
func SaveReceipt ¶
SaveReceipt writes a receipt JSON file and returns its path.
func ValidateContract ¶
ValidateContract rejects unknown schema majors and invalid requirement shapes.
func ValidateReceipt ¶
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.
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 ¶
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"`
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.
func ParsePolicy ¶
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 ¶
LoadReceipt loads a receipt by ID or absolute path.
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 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 (Report) HasObservedCoverage ¶
HasObservedCoverage reports whether a category has complete observed coverage.
func (Report) HasObservedCoverageScope ¶
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 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.