actioncontract

package
v1.5.0 Latest Latest
Warning

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

 Go to latest Published: Aug 24, 2026 License: Apache-2.0 Imports: 21 Imported by: 0

Documentation

Overview

Package actioncontract is Gait's explicit boundary for consuming Wrkr report-only proposed Action Contract artifacts. A proposal is evidence, never an authorization. Activation is a separate, signed object that can be handed to an execution boundary by an operator or authority.

Index

Constants

View Source 
const (
	ProposedSchemaID         = "https://wrkr.dev/schemas/v1/proposed-action-contract-artifact.schema.json"
	ProposedContractSchemaID = "https://wrkr.dev/schemas/v1/proposed-action-contract-v3.schema.json"
	ProposedSchemaVersion    = "1"
	ProposedContractVersion  = "3"
	ProposedProducer         = "wrkr"

	ActivatedSchemaID        = "https://gait.dev/schemas/v1/activated-action-contract-artifact.schema.json"
	ActivatedSchemaVersion   = "1"
	ActivatedContractVersion = "1"
	ActivatedProducer        = "gait"
)
View Source 
const (
	ReasonMalformedArtifact            = "artifact_malformed"
	ReasonUnsupportedArtifactSchema    = "artifact_schema_unsupported"
	ReasonUnsupportedContractSchema    = "contract_schema_unsupported"
	ReasonUnsupportedProducer          = "producer_unsupported"
	ReasonReportOnlyRequired           = "report_only_required"
	ReasonMissingContractID            = "contract_id_missing"
	ReasonMissingFamilyID              = "contract_family_id_missing"
	ReasonMissingCompositionRef        = "composition_ref_missing"
	ReasonMissingSourceRefs            = "source_refs_missing"
	ReasonMissingEvidenceRefs          = "evidence_refs_missing"
	ReasonRevisionInvalid              = "revision_invalid"
	ReasonRevisionIdentityMismatch     = "revision_identity_mismatch"
	ReasonContractIdentityMismatch     = "contract_identity_mismatch"
	ReasonArtifactIdentityMismatch     = "artifact_identity_mismatch"
	ReasonDigestMismatch               = "canonical_digest_mismatch"
	ReasonContractDigestMismatch       = "contract_digest_mismatch"
	ReasonUnsupportedConstraint        = "constraint_unsupported"
	ReasonStaleProposal                = "proposal_stale"
	ReasonSupersededProposal           = "proposal_superseded"
	ReasonContradictoryProposal        = "proposal_contradictory"
	ReasonActivationModeUnsupported    = "activation_mode_unsupported"
	ReasonPolicyDigestMissing          = "policy_digest_missing"
	ReasonPrincipalMissing             = "activating_principal_missing"
	ReasonAuthorityRefsMissing         = "authority_refs_missing"
	ReasonTargetMissing                = "target_missing"
	ReasonEnvironmentMissing           = "environment_missing"
	ReasonValidityInvalid              = "validity_invalid"
	ReasonRevisionReactivationRequired = "revision_reactivation_required"
	ReasonSelectionRequired            = "explicit_selection_required"
	ReasonAmbiguousSelection           = "ambiguous_selection"
	ReasonAuthorizationRequired        = "authorization_required"
	ReasonSchemaValidationFailed       = "schema_validation_failed"
	ReasonSigningKeyRequired           = "signing_key_required"
	ReasonDevelopmentSigningForbidden  = "development_signing_forbidden"
	ReasonDevelopmentSigningUnverified = "development_signing_unverified"
	ReasonSelectionEvidenceRequired    = "selection_evidence_required"
	ReasonSelectionMismatch            = "selection_mismatch"
	ReasonSelectionNotCurrent          = "selection_not_current"
	ReasonSelectionAmbiguous           = "selection_ambiguous"
	ReasonBindingMismatch              = "proposal_binding_mismatch"
	ReasonEvaluationTimeInvalid        = "evaluation_time_invalid"
	ReasonActivationNotYetValid        = "activation_not_yet_valid"
	ReasonActivationExpired            = "activation_expired"
)
View Source 
const (
	ExecutionEvidenceSchemaID            = "https://gait.dev/schemas/v1/action-contract/execution-evidence.schema.json"
	EffectEventSchemaID                  = "https://gait.dev/schemas/v1/action-contract/effect-event.schema.json"
	ContainmentEvidenceSchemaID          = "https://gait.dev/schemas/v1/action-contract/containment-evidence.schema.json"
	CompensationEvidenceSchemaID         = "https://gait.dev/schemas/v1/action-contract/compensation-evidence.schema.json"
	ExecutionEvidenceSchemaVersion       = "1"
	EvidenceProducer                     = "gait"
	MaxEvidenceBytes               int64 = 4 << 20
)
View Source 
const (
	ReasonConformanceInputMissing      = "conformance_input_missing"
	ReasonConformanceProposalInvalid   = "conformance_proposal_invalid"
	ReasonConformanceActivationInvalid = "conformance_activation_invalid"
	ReasonConformanceRuntimeInvalid    = "conformance_runtime_invalid"
	ReasonConformanceReadinessInvalid  = "conformance_readiness_invalid"
	ReasonConformanceLineageMissing    = "conformance_lineage_missing"
	ReasonConformanceLineageMismatch   = "conformance_lineage_mismatch"
	ReasonConformanceIdentifierOnly    = "conformance_identifier_only"
	ReasonConformanceEvidenceMissing   = "conformance_evidence_missing"
	ReasonConformanceReplay            = "conformance_replay"
	ReasonConformanceReordered         = "conformance_reordered"
	ReasonConformanceVerification      = "conformance_verification_failed"
)
View Source 
const (
	RuntimeActionSchemaID              = "https://gait.dev/schemas/v1/runtime-action.schema.json"
	RuntimeActionSchemaVersion         = "1"
	RuntimeClassificationInputSchemaID = "https://gait.dev/schemas/v1/runtime-classification-input.schema.json"
	RuntimeClassificationInputVersion  = "1"
	RuntimeReadinessSchemaID           = "https://gait.dev/schemas/v1/runtime-readiness.schema.json"
	RuntimeLifecycleSchemaID           = "https://gait.dev/schemas/v1/runtime-lifecycle-record.schema.json"
	RuntimeLifecycleVersion            = "1"
	ProofCompatibilityVersion          = "0.6.1"
	CorrelationProfileVersion          = "1.0"
)
View Source 
const (
	ActionClassRead             = "read"
	ActionClassWrite            = "write"
	ActionClassDeploy           = "deploy"
	ActionClassDelete           = "delete"
	ActionClassExecute          = "execute"
	ActionClassEgress           = "egress"
	ActionClassCredentialAccess = "credential_access" // #nosec G101 -- fixed classification vocabulary, not a credential.
	ActionClassRelease          = "release"
	ActionClassResource         = "resource"
)

These values intentionally include the classes emitted by Wrkr's released action-contract fixtures. The additional values are runtime-only classifications and do not change Wrkr's report semantics.

View Source 
const MaxRuntimeInputBytes int64 = 4 << 20
View Source 
const MaxRuntimeStages = 5

Variables

This section is empty.

Functions

func Activate 

func Activate(artifact Artifact, options ActivationOptions) (ActivatedArtifact, ValidationResult, error)

Activate validates one proposal and emits a deterministic signed activation object. No approval, authority, execution, or effect state is generated.

func CanonicalReadinessClaimDigest added in v1.5.0 

func CanonicalReadinessClaimDigest(input ReadinessInput, item ReadinessPrecondition) (string, error)

CanonicalReadinessClaimDigest binds a precondition to the contract and policy identity under which it was evaluated. This prevents a valid validator claim from being replayed for another contract or policy. The digest and signature fields, along with derived status/reason fields, are excluded so the signature binds the semantic claim rather than caller- supplied verification metadata or evaluator output.

func DecodeStrictRuntimeJSON added in v1.5.0 

func DecodeStrictRuntimeJSON(raw []byte, target any) error

DecodeStrictRuntimeJSON rejects duplicate keys, trailing values, unknown fields, and oversized payloads before any runtime decision is made.

func DevelopmentPublicKey 

func DevelopmentPublicKey() ed25519.PublicKey

DevelopmentPublicKey exposes the deterministic dev key's public half for local verification tests; production callers should use their configured key.

func EncodePrivateKey 

func EncodePrivateKey(privateKey ed25519.PrivateKey) string

EncodePrivateKey is a small helper for test/CLI fixtures and uses Proof's base64-compatible representation without making key material part of an artifact.

func RawDigest 

func RawDigest(raw []byte) string

RawDigest returns the byte SHA-256 used by conformance receipts.

func ReadEvidenceFile added in v1.5.0 

func ReadEvidenceFile(file *os.File) ([]byte, error)

func ReadRuntimeInput added in v1.5.0 

func ReadRuntimeInput(path string) ([]byte, error)

ReadRuntimeInput provides a descriptor-bound, bounded, no-follow read for explicit CLI JSON paths. It compares two descriptor reads and the final pathname identity so replacement/mutation races fail closed.

func RuntimeActionClassVocabulary added in v1.5.0 

func RuntimeActionClassVocabulary() []string

RuntimeVocabularies exposes the fixed compatibility vocabularies in sorted order for schema/fixture generators. Callers receive fresh slices.

func RuntimeCompositionRoleVocabulary added in v1.5.0 

func RuntimeCompositionRoleVocabulary() []string

func RuntimeDataClassVocabulary added in v1.5.0 

func RuntimeDataClassVocabulary() []string

func RuntimeOutcomeClassVocabulary added in v1.5.0 

func RuntimeOutcomeClassVocabulary() []string

func RuntimeResourceActionVocabulary added in v1.5.0 

func RuntimeResourceActionVocabulary() []string

func RuntimeTargetTrustClassVocabulary added in v1.5.0 

func RuntimeTargetTrustClassVocabulary() []string

func RuntimeTransitionClassVocabulary added in v1.5.0 

func RuntimeTransitionClassVocabulary() []string

func ValidateArtifactBytes 

func ValidateArtifactBytes(raw []byte, options ValidationOptions) (Artifact, ValidationResult)

func ValidateRuntimeAction added in v1.5.0 

func ValidateRuntimeAction(action RuntimeAction) []string

func VerifyActivation 

func VerifyActivation(artifact ActivatedArtifact, publicKey ed25519.PublicKey, proposal Artifact) (bool, error)

VerifyActivation checks the signed object against a supplied public key and the actual bound proposal. A signature alone is not a full activation verification result.

func VerifyActivationWithOptions 

func VerifyActivationWithOptions(artifact ActivatedArtifact, publicKey ed25519.PublicKey, options VerificationOptions) (bool, error)

func VerifyCompensationEvidence added in v1.5.0 

func VerifyCompensationEvidence(item CompensationEvidence, public ed25519.PublicKey) (bool, error)

func VerifyContainmentEvidence added in v1.5.0 

func VerifyContainmentEvidence(item ContainmentEvidence, public ed25519.PublicKey) (bool, error)

func VerifyEffectEvent added in v1.5.0 

func VerifyEffectEvent(item EffectEvent, public ed25519.PublicKey) (bool, error)

func VerifyExecutionEvidence added in v1.5.0 

func VerifyExecutionEvidence(item ExecutionEvidence, public ed25519.PublicKey) (bool, error)

func VerifyLifecycleRecord added in v1.5.0 

func VerifyLifecycleRecord(record LifecycleRecord, publicKey ed25519.PublicKey) (bool, error)

func WriteActivatedArtifact 

func WriteActivatedArtifact(path string, artifact ActivatedArtifact, overwrite bool) error

WriteActivatedArtifact writes deterministic bytes through a same-directory temporary file. Existing targets are refused unless overwrite is explicit; symlink targets and symlinked parent directories are always rejected.

func WriteEvidenceExclusive added in v1.5.0 

func WriteEvidenceExclusive(path string, value any) error

WriteEvidenceExclusive and ReadEvidenceFile are bounded, no-follow helpers for evidence handoff. The writer anchors all path operations to a verified directory descriptor and creates the destination exactly once. The reader accepts an already-open descriptor and never resolves a path itself.

Types

type ActionClassification added in v1.5.0 

type ActionClassification = RuntimeAction

Compatibility aliases keep the public vocabulary explicit for callers that refer to the three projections independently.

type ActivatedArtifact 

type ActivatedArtifact struct {
	SchemaID            string                `json:"schema_id"`
	SchemaVersion       string                `json:"schema_version"`
	ArtifactID          string                `json:"artifact_id"`
	ContractID          string                `json:"contract_id"`
	ContractFamilyID    string                `json:"contract_family_id"`
	Revision            int                   `json:"revision"`
	Producer            ProducerMetadata      `json:"producer"`
	Proposal            ActivationProposalRef `json:"proposal"`
	PolicyDigest        string                `json:"policy_digest"`
	ActivatingPrincipal string                `json:"activating_principal"`
	AuthorityRefs       []string              `json:"authority_refs"`
	Target              string                `json:"target"`
	Environment         string                `json:"environment"`
	ActivationMode      ActivationMode        `json:"activation_mode"`
	Validity            Validity              `json:"validity"`
	ExplicitExceptions  []string              `json:"explicit_exceptions"`
	ReportOnly          bool                  `json:"report_only"`
	DevelopmentSigning  bool                  `json:"development_signing"`
	Signature           proofsign.Signature   `json:"signature"`
}

func ParseActivatedArtifact 

func ParseActivatedArtifact(raw []byte) (ActivatedArtifact, error)

func ReadActivatedArtifact 

func ReadActivatedArtifact(path string) (ActivatedArtifact, []byte, error)

type ActivationMode 

type ActivationMode string
const (
	ActivationContextOnly  ActivationMode = "context_only"
	ActivationEnforceFloor ActivationMode = "enforce_floor"
	ActivationRequired     ActivationMode = "required"
)

type ActivationOptions 

type ActivationOptions struct {
	PolicyDigest            string
	ActivatingPrincipal     string
	AuthorityRefs           []string
	Target                  string
	Environment             string
	Mode                    ActivationMode
	ValidFrom               string
	ValidUntil              string
	ExplicitExceptions      []string
	SigningPrivateKey       ed25519.PrivateKey
	AllowDevelopmentSigning bool
	Selection               *SelectionEvidence
	EvaluationTime          time.Time
}

type ActivationProposalRef 

type ActivationProposalRef struct {
	ArtifactID             string `json:"artifact_id"`
	CanonicalContentDigest string `json:"canonical_content_digest"`
	ContractID             string `json:"contract_id"`
	ContractFamilyID       string `json:"contract_family_id"`
	Revision               int    `json:"revision"`
	SchemaID               string `json:"schema_id"`
	SchemaVersion          string `json:"schema_version"`
	ContractSchemaVersion  string `json:"contract_schema_version"`
}

type ActivationResult 

type ActivationResult struct {
	Activated  ActivatedArtifact `json:"activated"`
	Validation ValidationResult  `json:"validation"`
}

type Artifact 

type Artifact struct {
	SchemaID               string           `json:"schema_id"`
	SchemaVersion          string           `json:"schema_version"`
	ArtifactID             string           `json:"artifact_id"`
	ContractID             string           `json:"contract_id"`
	ContractFamilyID       string           `json:"contract_family_id"`
	Revision               int              `json:"revision"`
	Producer               ProducerMetadata `json:"producer"`
	SourceScanRefs         []string         `json:"source_scan_refs"`
	CompositionRefs        []string         `json:"composition_refs"`
	ResolutionKey          string           `json:"resolution_key,omitempty"`
	CreationEvidence       []string         `json:"creation_evidence"`
	CanonicalContentDigest string           `json:"canonical_content_digest"`
	Variant                VariantMetadata  `json:"variant"`
	ReportOnly             bool             `json:"report_only"`
	Contract               map[string]any   `json:"contract"`
}

Artifact is intentionally map-backed for the embedded contract. This lets Gait preserve Wrkr's immutable v3 contract without reimplementing Wrkr's risk model or dropping future additive fields.

func ParseArtifact 

func ParseArtifact(raw []byte) (Artifact, error)

ParseArtifact parses one standalone artifact, rejects duplicate keys and trailing JSON, and preserves JSON numbers for JCS digest verification.

func ReadArtifact 

func ReadArtifact(path string) (Artifact, []byte, error)

ReadArtifact reads exactly one artifact from path. The path is a caller selection; no directory scanning or recommendation discovery is performed.

type BoundaryClassification added in v1.5.0 

type BoundaryClassification = RuntimeBoundary

type ClassificationInput added in v1.5.0 

type ClassificationInput struct {
	SchemaID                 string               `json:"schema_id"`
	SchemaVersion            string               `json:"schema_version"`
	ActionID                 string               `json:"action_id"`
	ActionClass              string               `json:"action_class"`
	ActionClasses            []string             `json:"action_classes"`
	CompositionRole          string               `json:"composition_role"`
	DataClasses              []string             `json:"data_classes"`
	TargetTrustClass         string               `json:"target_trust_class"`
	TransitionClass          string               `json:"transition_class"`
	ExpectedOutcomeClass     string               `json:"expected_outcome_class"`
	IntendedOutcomeClass     string               `json:"intended_outcome_class"`
	ResourceLifecycleActions []string             `json:"resource_lifecycle_actions"`
	ResourceActions          []string             `json:"resource_actions"`
	RiskClass                string               `json:"risk_class"`
	TargetRef                string               `json:"target_ref"`
	SourceTrustClass         string               `json:"source_trust_class"`
	BoundaryRefs             []string             `json:"boundary_refs"`
	ProofRefs                []string             `json:"proof_refs"`
	Stages                   []RuntimeActionStage `json:"stages"`
	Hints                    []string             `json:"hints"`
}

ClassificationInput is intentionally small. Supplied values are never lowered by inference; inference may only preserve or raise the effective action class/control posture.

func ParseClassificationInput added in v1.5.0 

func ParseClassificationInput(raw []byte) (ClassificationInput, error)

type ClassificationResult added in v1.5.0 

type ClassificationResult struct {
	Action      RuntimeAction `json:"action"`
	Valid       bool          `json:"valid"`
	ReasonCodes []string      `json:"reason_codes,omitempty"`
}

func ClassifyAction added in v1.5.0 

func ClassifyAction(input ClassificationInput) ClassificationResult

ClassifyAction is the concise library entry point used by adapters.

func ClassifyArtifact added in v1.5.0 

func ClassifyArtifact(artifact Artifact) ClassificationResult

ClassifyArtifact projects the immutable Wrkr proposal without mutating it.

func ClassifyRuntimeAction added in v1.5.0 

func ClassifyRuntimeAction(input ClassificationInput) ClassificationResult

ClassifyRuntimeAction deterministically normalizes a runtime action. It does not inspect the network, run validators, or infer observed effects.

type CompensationEvidence added in v1.5.0 

type CompensationEvidence struct {
	SchemaID               string                `json:"schema_id"`
	SchemaVersion          string                `json:"schema_version"`
	EvidenceID             string                `json:"evidence_id"`
	Binding                EvidenceBinding       `json:"binding"`
	EventRef               proof.RelationshipRef `json:"event_ref"`
	RequirementRef         proof.RelationshipRef `json:"requirement_ref"`
	ExecutionRef           proof.RelationshipRef `json:"execution_ref"`
	OccurredAt             string                `json:"occurred_at"`
	FreshUntil             string                `json:"fresh_until"`
	Outcome                string                `json:"outcome"`
	ReasonCode             string                `json:"reason_code"`
	Provenance             EvidenceProvenance    `json:"provenance"`
	CanonicalContentDigest string                `json:"canonical_content_digest"`
}

func NewCompensationEvidence added in v1.5.0 

func NewCompensationEvidence(item CompensationEvidence, private ed25519.PrivateKey) (CompensationEvidence, error)

func ParseCompensationEvidence added in v1.5.0 

func ParseCompensationEvidence(raw []byte) (CompensationEvidence, error)

type ContainmentEvidence added in v1.5.0 

type ContainmentEvidence struct {
	SchemaID               string                `json:"schema_id"`
	SchemaVersion          string                `json:"schema_version"`
	EvidenceID             string                `json:"evidence_id"`
	Binding                EvidenceBinding       `json:"binding"`
	EventRef               proof.RelationshipRef `json:"event_ref"`
	ExecutionRef           proof.RelationshipRef `json:"execution_ref"`
	EffectRef              proof.RelationshipRef `json:"effect_ref"`
	ContainmentRef         proof.RelationshipRef `json:"containment_ref"`
	OccurredAt             string                `json:"occurred_at"`
	FreshUntil             string                `json:"fresh_until"`
	Outcome                string                `json:"outcome"`
	ReasonCode             string                `json:"reason_code"`
	Provenance             EvidenceProvenance    `json:"provenance"`
	CanonicalContentDigest string                `json:"canonical_content_digest"`
}

func NewContainmentEvidence added in v1.5.0 

func NewContainmentEvidence(item ContainmentEvidence, private ed25519.PrivateKey) (ContainmentEvidence, error)

func ParseContainmentEvidence added in v1.5.0 

func ParseContainmentEvidence(raw []byte) (ContainmentEvidence, error)

type ControlMode added in v1.5.0 

type ControlMode string
const (
	ControlModeEnforced     ControlMode = "enforced"
	ControlModeObserved     ControlMode = "observed"
	ControlModeSelfAttested ControlMode = "self_attested"
	ControlModeUnknown      ControlMode = "unknown"
)

type EffectEvent added in v1.5.0 

type EffectEvent struct {
	SchemaID               string                `json:"schema_id"`
	SchemaVersion          string                `json:"schema_version"`
	EvidenceID             string                `json:"evidence_id"`
	Binding                EvidenceBinding       `json:"binding"`
	EventRef               proof.RelationshipRef `json:"event_ref"`
	ExecutionRef           proof.RelationshipRef `json:"execution_ref"`
	EffectRef              proof.RelationshipRef `json:"effect_ref"`
	OccurredAt             string                `json:"occurred_at"`
	FreshUntil             string                `json:"fresh_until"`
	Outcome                string                `json:"outcome"`
	ReasonCode             string                `json:"reason_code"`
	Provenance             EvidenceProvenance    `json:"provenance"`
	CanonicalContentDigest string                `json:"canonical_content_digest"`
}

func NewEffectEvent added in v1.5.0 

func NewEffectEvent(item EffectEvent, private ed25519.PrivateKey) (EffectEvent, error)

func ParseEffectEvent added in v1.5.0 

func ParseEffectEvent(raw []byte) (EffectEvent, error)

type EvidenceBinding added in v1.5.0 

type EvidenceBinding struct {
	ContractFamilyID string                                   `json:"contract_family_id"`
	Revision         int                                      `json:"revision"`
	ContractRef      proof.RelationshipRef                    `json:"contract_ref"`
	ActivationRef    proof.RelationshipRef                    `json:"activation_ref"`
	RuntimeActionRef proof.RelationshipRef                    `json:"runtime_action_ref"`
	ReadinessRef     proof.RelationshipRef                    `json:"readiness_ref"`
	DecisionRef      proof.RelationshipRef                    `json:"decision_ref"`
	PolicyRef        proof.RelationshipRef                    `json:"policy_ref"`
	TargetRef        proof.RelationshipRef                    `json:"target_ref"`
	EnvironmentRef   proof.RelationshipRef                    `json:"environment_ref"`
	ProofRefs        []proof.RelationshipRef                  `json:"proof_refs"`
	CausalRefs       []proof.RelationshipRef                  `json:"causal_refs"`
	Correlation      proof.ControlContainmentTelemetryProfile `json:"correlation"`
}

func (EvidenceBinding) RelationshipRefs added in v1.5.0 

func (b EvidenceBinding) RelationshipRefs() []proof.RelationshipRef

func (EvidenceBinding) Validate added in v1.5.0 

func (b EvidenceBinding) Validate() error

type EvidenceProvenance added in v1.5.0 

type EvidenceProvenance struct {
	Producer  string              `json:"producer"`
	Writer    string              `json:"writer"`
	Verifier  string              `json:"verifier"`
	PublicKey string              `json:"public_key"`
	Signature proofsign.Signature `json:"signature"`
}

type ExecutionEvidence added in v1.5.0 

type ExecutionEvidence struct {
	SchemaID               string                `json:"schema_id"`
	SchemaVersion          string                `json:"schema_version"`
	EvidenceID             string                `json:"evidence_id"`
	Binding                EvidenceBinding       `json:"binding"`
	EventRef               proof.RelationshipRef `json:"event_ref"`
	OccurredAt             string                `json:"occurred_at"`
	FreshUntil             string                `json:"fresh_until"`
	Outcome                string                `json:"outcome"`
	ReasonCode             string                `json:"reason_code"`
	CompensationRequired   bool                  `json:"compensation_required"`
	Provenance             EvidenceProvenance    `json:"provenance"`
	CanonicalContentDigest string                `json:"canonical_content_digest"`
}

func NewExecutionEvidence added in v1.5.0 

func NewExecutionEvidence(item ExecutionEvidence, private ed25519.PrivateKey) (ExecutionEvidence, error)

func ParseExecutionEvidence added in v1.5.0 

func ParseExecutionEvidence(raw []byte) (ExecutionEvidence, error)

type LifecycleConformanceExpectation added in v1.5.0 

type LifecycleConformanceExpectation struct {
	ExecutionOutcome    string `json:"execution_outcome,omitempty"`
	EffectOutcome       string `json:"effect_outcome,omitempty"`
	ContainmentOutcome  string `json:"containment_outcome,omitempty"`
	CompensationOutcome string `json:"compensation_outcome,omitempty"`
	RequireComplete     bool   `json:"require_complete,omitempty"`
}

LifecycleConformanceExpectation describes the terminal path that a fixture or caller expects. Empty values mean that the corresponding stage is not required (for example a blocked-before-execution path).

type LifecycleConformanceInput added in v1.5.0 

type LifecycleConformanceInput struct {
	Proposal                      Artifact
	Activation                    ActivatedArtifact
	ActivationPublicKey           ed25519.PublicKey
	RuntimeAction                 RuntimeAction
	Readiness                     ReadinessResult
	ReadinessTrustedValidatorRefs []string
	ReadinessTrustedValidatorKeys map[string]ed25519.PublicKey
	LifecycleRecords              []LifecycleRecord
	LifecyclePublicKey            ed25519.PublicKey
	EvaluationTime                time.Time
	AllowDevelopmentSign          bool
	Expectation                   LifecycleConformanceExpectation
}

LifecycleConformanceInput is deliberately composed of already parsed artifacts. File loading and execution are outside this API.

type LifecycleConformanceResult added in v1.5.0 

type LifecycleConformanceResult struct {
	Valid                bool               `json:"valid"`
	AuthoritativeSuccess bool               `json:"authoritative_success"`
	ReasonCodes          []string           `json:"reason_codes,omitempty"`
	Snapshot             *LifecycleSnapshot `json:"snapshot,omitempty"`
}

func GradeLifecycleConformance added in v1.5.0 

func GradeLifecycleConformance(input LifecycleConformanceInput) LifecycleConformanceResult

GradeLifecycleConformance is the verb-oriented alias used by regression adapters. It is intentionally pure and has no filesystem or tool access.

func VerifyLifecycleConformance added in v1.5.0 

func VerifyLifecycleConformance(input LifecycleConformanceInput) LifecycleConformanceResult

VerifyLifecycleConformance verifies the complete proposal -> activation -> readiness -> execution -> effect -> containment/compensation chain. It returns a stable reason code instead of treating an incomplete or identifier-only correlation as a successful partial result.

type LifecycleEventKind added in v1.5.0 

type LifecycleEventKind string

Lifecycle records are signed, digest-bound state transitions. ReduceLifecycle is a pure reducer over records; it does not persist or append to an event store and it preserves the immutable proposal/activation references. 

const (
	LifecycleProposalIngested      LifecycleEventKind = "proposal_ingested"
	LifecycleActivationRequested   LifecycleEventKind = "activation_requested"
	LifecycleActivated             LifecycleEventKind = "activated"
	LifecycleRejected              LifecycleEventKind = "rejected"
	LifecycleRevoked               LifecycleEventKind = "revoked"
	LifecycleSuperseded            LifecycleEventKind = "superseded"
	LifecyclePreconditionEvaluated LifecycleEventKind = "precondition_evaluated"
	LifecycleDecisionReady         LifecycleEventKind = "decision_ready"
	LifecycleExecutionStarted      LifecycleEventKind = "execution_started"
	LifecycleExecutionSucceeded    LifecycleEventKind = "execution_succeeded"
	LifecycleExecutionFailed       LifecycleEventKind = "execution_failed"
	LifecycleExecutionBlocked      LifecycleEventKind = "execution_blocked"
	LifecycleEffectRecorded        LifecycleEventKind = "effect_recorded"
	LifecycleEffectValidated       LifecycleEventKind = "effect_validated"
	LifecycleContainmentRequested  LifecycleEventKind = "containment_requested"
	LifecycleContainmentCompleted  LifecycleEventKind = "containment_completed"
	LifecycleContainmentPartial    LifecycleEventKind = "containment_partial"
	LifecycleContainmentUnresolved LifecycleEventKind = "containment_unresolved"
	LifecycleCompensationRequired  LifecycleEventKind = "compensation_required"
	LifecycleCompensationStarted   LifecycleEventKind = "compensation_started"
	LifecycleCompensationCompleted LifecycleEventKind = "compensation_completed"
)

type LifecycleRecord added in v1.5.0 

type LifecycleRecord struct {
	SchemaID         string                                   `json:"schema_id"`
	SchemaVersion    string                                   `json:"schema_version"`
	RecordID         string                                   `json:"record_id"`
	Kind             LifecycleEventKind                       `json:"kind"`
	OccurredAt       string                                   `json:"occurred_at"`
	ContractRef      proof.RelationshipRef                    `json:"contract_ref"`
	ContractFamilyID string                                   `json:"contract_family_id,omitempty"`
	Revision         int                                      `json:"revision"`
	ProposalRef      *proof.RelationshipRef                   `json:"proposal_ref,omitempty"`
	ActivationRef    *proof.RelationshipRef                   `json:"activation_ref,omitempty"`
	PreconditionRefs []proof.RelationshipRef                  `json:"precondition_refs,omitempty"`
	Decision         *ReadinessResult                         `json:"decision,omitempty"`
	EvidenceRefs     []proof.RelationshipRef                  `json:"evidence_refs,omitempty"`
	Execution        *ExecutionEvidence                       `json:"execution,omitempty"`
	Effect           *EffectEvent                             `json:"effect,omitempty"`
	Containment      *ContainmentEvidence                     `json:"containment,omitempty"`
	Compensation     *CompensationEvidence                    `json:"compensation,omitempty"`
	ReasonCodes      []string                                 `json:"reason_codes,omitempty"`
	Correlation      proof.ControlContainmentTelemetryProfile `json:"correlation"`
	ImmutableObject  json.RawMessage                          `json:"immutable_object,omitempty"`
	Signature        proofsign.Signature                      `json:"signature"`
}

func NewLifecycleRecord added in v1.5.0 

func NewLifecycleRecord(options LifecycleRecordOptions) (LifecycleRecord, error)

func ParseLifecycleRecord added in v1.5.0 

func ParseLifecycleRecord(raw []byte) (LifecycleRecord, error)

ParseLifecycleRecord is the strict JSON boundary for persisted lifecycle records; callers must verify the returned record before reducing it.

type LifecycleRecordOptions added in v1.5.0 

type LifecycleRecordOptions struct {
	Kind              LifecycleEventKind
	OccurredAt        time.Time
	ContractRef       proof.RelationshipRef
	ContractFamilyID  string
	Revision          int
	ProposalRef       *proof.RelationshipRef
	ActivationRef     *proof.RelationshipRef
	PreconditionRefs  []proof.RelationshipRef
	Decision          *ReadinessResult
	EvidenceRefs      []proof.RelationshipRef
	Execution         *ExecutionEvidence
	Effect            *EffectEvent
	Containment       *ContainmentEvidence
	Compensation      *CompensationEvidence
	ReasonCodes       []string
	Correlation       proof.ControlContainmentTelemetryProfile
	ImmutableObject   json.RawMessage
	SigningPrivateKey ed25519.PrivateKey
}

type LifecycleSnapshot added in v1.5.0 

type LifecycleSnapshot struct {
	ProposalIngested       bool              `json:"proposal_ingested"`
	ActivationRequested    bool              `json:"activation_requested"`
	Activated              bool              `json:"activated"`
	Rejected               bool              `json:"rejected"`
	Revoked                bool              `json:"revoked"`
	Superseded             bool              `json:"superseded"`
	DecisionReady          bool              `json:"decision_ready"`
	PreconditionsEvaluated int               `json:"preconditions_evaluated"`
	ExecutionStatus        string            `json:"execution_status,omitempty"`
	EffectStatus           string            `json:"effect_status,omitempty"`
	ContainmentStatus      string            `json:"containment_status,omitempty"`
	CompensationStatus     string            `json:"compensation_status,omitempty"`
	CurrentStatus          string            `json:"current_status"`
	ReasonCodes            []string          `json:"reason_codes,omitempty"`
	Records                []LifecycleRecord `json:"records"`
}

func ReduceLifecycle added in v1.5.0 

func ReduceLifecycle(records []LifecycleRecord) LifecycleSnapshot

func ReduceLifecycleChecked added in v1.5.0 

func ReduceLifecycleChecked(records []LifecycleRecord) (LifecycleSnapshot, error)

ReduceLifecycleChecked validates structural identity, timestamps, contract isolation, duplicate IDs, and terminal ordering before applying the pure reduction. It does not verify signatures; use ReduceVerifiedLifecycle when the result is used as authoritative lifecycle state.

func ReduceLifecycleEvents added in v1.5.0 

func ReduceLifecycleEvents(records []LifecycleRecord) LifecycleSnapshot

ReduceLifecycleEvents is a compatibility alias with the event-oriented wording used by integrations; both names remain pure reducers.

func ReduceVerifiedLifecycle added in v1.5.0 

func ReduceVerifiedLifecycle(records []LifecycleRecord, publicKey ed25519.PublicKey) (LifecycleSnapshot, error)

ReduceVerifiedLifecycle verifies every record with the trusted public key before applying the structural pure reducer. A failed verification is authoritative failure and never falls back to structural reduction.

type ObservedEffect added in v1.5.0 

type ObservedEffect struct {
	Status      string   `json:"status"` // not_observed|observed|contradictory
	EffectClass string   `json:"effect_class,omitempty"`
	EffectRefs  []string `json:"effect_refs,omitempty"`
	ObservedAt  string   `json:"observed_at,omitempty"`
}

type OutcomeClassification added in v1.5.0 

type OutcomeClassification = ObservedEffect

type ProducerMetadata 

type ProducerMetadata struct {
	Name                  string `json:"name"`
	ArtifactSchemaVersion string `json:"artifact_schema_version"`
	ContractSchemaVersion string `json:"contract_schema_version"`
}

ProducerMetadata is the producer declaration carried by a proposal.

type ReadinessInput added in v1.5.0 

type ReadinessInput struct {
	ContractID           string                       `json:"contract_id,omitempty"`
	Preconditions        []ReadinessPrecondition      `json:"preconditions"`
	TrustedValidatorRefs []string                     `json:"trusted_validator_refs,omitempty"`
	PolicyDigest         string                       `json:"policy_digest,omitempty"`
	Now                  time.Time                    `json:"-"`
	TrustedValidatorKeys map[string]ed25519.PublicKey `json:"-"`
}

func ParseReadinessInput added in v1.5.0 

func ParseReadinessInput(raw []byte) (ReadinessInput, error)

type ReadinessPrecondition added in v1.5.0 

type ReadinessPrecondition struct {
	RequirementID       string          `json:"requirement_id"`
	Kind                string          `json:"kind"`
	Required            bool            `json:"required"`
	RequiredConstraint  string          `json:"required_constraint,omitempty"`
	ContractRef         string          `json:"contract_ref,omitempty"`
	ObservedValue       string          `json:"observed_value,omitempty"`
	ObservedResult      string          `json:"observed_result,omitempty"`
	ObservedAt          string          `json:"observed_at,omitempty"`
	MaxAgeSeconds       int64           `json:"max_age_seconds,omitempty"`
	TTLSeconds          int64           `json:"ttl_seconds,omitempty"`
	Environment         string          `json:"environment,omitempty"`
	Target              string          `json:"target,omitempty"`
	SandboxStatus       string          `json:"sandbox_status,omitempty"`
	CredentialMode      string          `json:"credential_mode,omitempty"`
	ResourceStatus      string          `json:"resource_status,omitempty"`
	CompensationStatus  string          `json:"compensation_status,omitempty"`
	EvidenceDigest      string          `json:"evidence_digest,omitempty"`
	ValidatorSignature  string          `json:"validator_signature,omitempty"`
	Producer            string          `json:"producer,omitempty"`
	AcceptableProducers []string        `json:"acceptable_producers,omitempty"`
	EvidenceState       string          `json:"evidence_state,omitempty"`
	FreshnessState      string          `json:"freshness_state,omitempty"`
	EvidenceRefs        []string        `json:"evidence_refs,omitempty"`
	BoundaryRefs        []string        `json:"boundary_refs,omitempty"`
	ControlMode         ControlMode     `json:"control_mode"`
	Status              ReadinessStatus `json:"status"`
	ReasonCodes         []string        `json:"reason_codes,omitempty"`
}

type ReadinessResult added in v1.5.0 

type ReadinessResult struct {
	SchemaID      string                  `json:"schema_id"`
	SchemaVersion string                  `json:"schema_version"`
	ContractID    string                  `json:"contract_id,omitempty"`
	PolicyDigest  string                  `json:"policy_digest,omitempty"`
	Ready         bool                    `json:"ready"`
	Status        ReadinessStatus         `json:"status"`
	Preconditions []ReadinessPrecondition `json:"preconditions"`
	ReasonCodes   []string                `json:"reason_codes,omitempty"`
}

func EvaluateContractReadiness added in v1.5.0 

func EvaluateContractReadiness(input ReadinessInput) ReadinessResult

EvaluateContractReadiness is the stable name for callers evaluating a typed contract projection.

func EvaluateReadiness added in v1.5.0 

func EvaluateReadiness(input ReadinessInput) ReadinessResult

EvaluateReadiness applies only policy-named trusted validator references. Wrkr declarations and judge/self-attestation labels are intentionally not trusted by default.

func ReadinessFromArtifact added in v1.5.0 

func ReadinessFromArtifact(artifact Artifact, options ReadinessInput) ReadinessResult

func ReadinessFromContract added in v1.5.0 

func ReadinessFromContract(contract map[string]any, options ReadinessInput) ReadinessResult

type ReadinessStatus added in v1.5.0 

type ReadinessStatus string

ReadinessStatus is per requirement. A required inconclusive result is never promoted to satisfied. 

const (
	ReadinessSatisfied    ReadinessStatus = "satisfied"
	ReadinessUnsatisfied  ReadinessStatus = "unsatisfied"
	ReadinessInconclusive ReadinessStatus = "inconclusive"
	ReadinessNotRequired  ReadinessStatus = "not_required"
)

type RuntimeAction added in v1.5.0 

type RuntimeAction struct {
	SchemaID                 string               `json:"schema_id"`
	SchemaVersion            string               `json:"schema_version"`
	ActionID                 string               `json:"action_id"`
	ActionClass              string               `json:"action_class"`
	ActionClasses            []string             `json:"action_classes,omitempty"`
	CompositionRole          string               `json:"composition_role"`
	DataClasses              []string             `json:"data_classes,omitempty"`
	TargetTrustClass         string               `json:"target_trust_class"`
	TransitionClass          string               `json:"transition_class"`
	ExpectedOutcomeClass     string               `json:"expected_outcome_class"`
	IntendedOutcomeClass     string               `json:"intended_outcome_class"`
	ResourceLifecycleActions []string             `json:"resource_lifecycle_actions,omitempty"`
	ResourceActions          []string             `json:"resource_actions,omitempty"`
	RiskClass                string               `json:"risk_class,omitempty"`
	TargetRef                string               `json:"target_ref,omitempty"`
	Boundary                 RuntimeBoundary      `json:"boundary"`
	Stages                   []RuntimeActionStage `json:"stages,omitempty"`
	ObservedEffect           *ObservedEffect      `json:"observed_effect,omitempty"`
	InferenceReasons         []string             `json:"inference_reasons,omitempty"`
	ClassificationReasons    []string             `json:"classification_reasons,omitempty"`
}

RuntimeAction is a versioned pre-execution classification. RiskClass is intentionally independent of ResourceLifecycleActions: an action can reserve/cleanup a resource without changing its risk classification.

func ParseRuntimeAction added in v1.5.0 

func ParseRuntimeAction(raw []byte) (RuntimeAction, error)

ParseRuntimeAction parses the documented runtime-action artifact emitted as the classification.action object. It is distinct from ClassificationInput, which is the heuristic/raw-input surface used with --input.

type RuntimeActionStage added in v1.5.0 

type RuntimeActionStage struct {
	StageID          string   `json:"stage_id"`
	Role             string   `json:"role"`
	ActionClasses    []string `json:"action_classes,omitempty"`
	DataClasses      []string `json:"data_classes,omitempty"`
	TargetTrustClass string   `json:"target_trust_class"`
	TransitionClass  string   `json:"transition_class"`
	ExpectedOutcome  string   `json:"expected_outcome_class"`
	TargetRef        string   `json:"target_ref,omitempty"`
	BoundaryRefs     []string `json:"boundary_refs,omitempty"`
}

RuntimeActionStage is bounded (at most MaxRuntimeStages) to keep the representation a hypothesis rather than an unbounded graph/event store.

type RuntimeBoundary added in v1.5.0 

type RuntimeBoundary struct {
	SourceTrustClass string   `json:"source_trust_class"`
	TargetTrustClass string   `json:"target_trust_class"`
	TransitionClass  string   `json:"transition_class"`
	BoundaryRefs     []string `json:"boundary_refs,omitempty"`
	ProofRefs        []string `json:"proof_refs,omitempty"`
}

RuntimeBoundary keeps boundary references separate from evidence refs. A boundary ref is a relationship to a trust boundary, not proof that the boundary enforced anything.

type SelectionEvidence 

type SelectionEvidence struct {
	ArtifactID             string `json:"artifact_id"`
	ArtifactSHA256         string `json:"artifact_sha256"`
	CanonicalContentDigest string `json:"canonical_content_digest"`
	ContractID             string `json:"contract_id"`
	ContractFamilyID       string `json:"contract_family_id"`
	Revision               int    `json:"revision"`
	Current                bool   `json:"current"`
}

SelectionEvidence is the Gait-owned current-selection record required before activation or consumer handoff. It binds one explicit artifact to the family/revision currently selected by the caller.

func LoadSelectionEvidence 

func LoadSelectionEvidence(path, artifactPath string, artifact Artifact, raw []byte) (SelectionEvidence, error)

type SupportedConstraintSummary 

type SupportedConstraintSummary struct {
	TargetConstraintKeys []string `json:"target_constraint_keys"`
	PreconditionKinds    []string `json:"precondition_kinds"`
	AuthorityKinds       []string `json:"authority_kinds"`
	Unsupported          []string `json:"unsupported,omitempty"`
}

type ValidationError 

type ValidationError struct{ Reasons []string }

ValidationError is stable and machine-readable. Error() is intentionally compact because CLI JSON exposes Reasons directly.

func (*ValidationError) Error 

func (e *ValidationError) Error() string

type ValidationOptions 

type ValidationOptions struct {
	Now                 time.Time
	RequireExplicitPath bool
	ExpectedContractID  string
	ExpectedFamilyID    string
	ExpectedRevision    int
	SchemaRoot          string
}

ValidationOptions controls time-sensitive checks. A zero Now uses the current UTC time; callers that need reproducibility should pass a fixed Now.

type ValidationResult 

type ValidationResult struct {
	Valid                  bool                       `json:"valid"`
	Reasons                []string                   `json:"reason_codes,omitempty"`
	Artifact               *Artifact                  `json:"artifact,omitempty"`
	CanonicalContentDigest string                     `json:"canonical_content_digest,omitempty"`
	SupportedConstraints   SupportedConstraintSummary `json:"supported_constraints"`
}

func ValidateArtifact 

func ValidateArtifact(artifact Artifact, options ValidationOptions) ValidationResult

ValidateArtifact validates an explicit Wrkr v3 proposal and its JCS envelope digest. It does not activate or infer authority.

type Validity 

type Validity struct {
	NotBefore string `json:"not_before"`
	NotAfter  string `json:"not_after,omitempty"`
}

type VariantMetadata 

type VariantMetadata struct {
	ShareProfile string `json:"share_profile"`
	Redacted     bool   `json:"redacted"`
}

type VerificationOptions 

type VerificationOptions struct {
	AllowDevelopmentSigning bool
	Proposal                *Artifact
	// EvaluationTime controls activation and proposal expiry checks. A zero
	// value preserves the library's historical current-time behavior; CLI and
	// deterministic callers should pass an explicit UTC time.
	EvaluationTime time.Time
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.