domain

package
v0.2.1 Latest Latest
Warning

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

 Go to latest Published: Aug 7, 2026 License: MIT Imports: 19 Imported by: 0

Documentation

Overview

Package domain defines provider-neutral Goalrail semantics.

Types in this package must not depend on workflow runtimes, model vendors, authorization engines, sandbox providers, OpenSpec, or observability SDKs.

Index

Constants

View Source 
const (
	AdmissionPacketSchemaV1 = "goalrail.admission-packet/v1"
	AdmissionResultSchemaV1 = "goalrail.admission-result/v1"
	MaxAdmissionPacketBytes = 256 << 10
	MaxAdmissionResultBytes = 256 << 10
	MaxAdmissionEvidence    = 512
	MaxAdmissionPaths       = 4096
	MaxAdmissionReasons     = 256

	AdmissionValid      AdmissionClassification = "VALID"
	AdmissionMissing    AdmissionClassification = "MISSING"
	AdmissionAmbiguous  AdmissionClassification = "AMBIGUOUS"
	AdmissionInvalid    AdmissionClassification = "INVALID"
	AdmissionExempted   AdmissionClassification = "EXEMPTED"
	AdmissionBreakGlass AdmissionClassification = "BREAK_GLASS"
	AdmissionBootstrap  AdmissionClassification = "BOOTSTRAP"

	AdmissionAllow AdmissionOutcome = "allow"
	AdmissionDeny  AdmissionOutcome = "deny"

	ReasonDeclarationInvalid       AdmissionReasonCode = "DECLARATION_INVALID"
	ReasonPolicyConflict           AdmissionReasonCode = "POLICY_CONFLICT"
	ReasonMaterialPathUnbound      AdmissionReasonCode = "MATERIAL_PATH_UNBOUND"
	ReasonIntentUnconfirmed        AdmissionReasonCode = "INTENT_UNCONFIRMED"
	ReasonChangeMismatch           AdmissionReasonCode = "CHANGE_MISMATCH"
	ReasonWorkSpecMissing          AdmissionReasonCode = "WORK_SPEC_MISSING"
	ReasonRunSessionMissing        AdmissionReasonCode = "RUN_SESSION_MISSING"
	ReasonPullRequestMissing       AdmissionReasonCode = "PULL_REQUEST_MISSING"
	ReasonReviewMissing            AdmissionReasonCode = "REVIEW_MISSING"
	ReasonCheckMissing             AdmissionReasonCode = "CHECK_MISSING"
	ReasonReceiptMissing           AdmissionReasonCode = "RECEIPT_MISSING"
	ReasonOwnerDecisionMissing     AdmissionReasonCode = "OWNER_DECISION_MISSING"
	ReasonLineageConflict          AdmissionReasonCode = "LINEAGE_CONFLICT"
	ReasonExceptionExpired         AdmissionReasonCode = "EXCEPTION_EXPIRED"
	ReasonExceptionScopeMismatch   AdmissionReasonCode = "EXCEPTION_SCOPE_MISMATCH"
	ReasonActivationUnverified     AdmissionReasonCode = "ACTIVATION_UNVERIFIED"
	ReasonBootstrapRange           AdmissionReasonCode = "BOOTSTRAP_RANGE"
	ReasonExceptionApplied         AdmissionReasonCode = "EXCEPTION_APPLIED"
	ReasonTrustedTimeMissing       AdmissionReasonCode = "TRUSTED_TIME_MISSING"
	ReasonPacketInvalid            AdmissionReasonCode = "PACKET_INVALID"
	ReasonProvenanceUntrusted      AdmissionReasonCode = "PROVENANCE_UNTRUSTED"
	ReasonRangeMismatch            AdmissionReasonCode = "RANGE_MISMATCH"
	ReasonGeneratedEvidenceMissing AdmissionReasonCode = "GENERATED_EVIDENCE_MISSING"
)
View Source 
const (
	CanaryAssignmentCount              = uint32(15)
	CanaryMinimumVerifiedLineage       = uint32(13)
	CanaryMaximumMedianOverheadMinutes = float64(30)
	CanaryUnresolvedLinkStopCount      = uint32(2)
	CanaryProcessAbandonmentStopCount  = uint32(3)
)
View Source 
const (
	WorkUnitSchemaV1     = "goalrail.work-unit/v1"
	LineageEventSchemaV1 = "goalrail.lineage-event/v1"
	MaxWorkUnitBytes     = 128 << 10
	MaxLineageEventBytes = 128 << 10
	MaxLineageReferences = 256
	MaxLineageRelations  = 128

	RelationSingle RelationCardinality = "single"
	RelationSet    RelationCardinality = "set"

	WorkUnitOpen           WorkUnitLifecycleState = "open"
	WorkUnitAdmissionReady WorkUnitLifecycleState = "admission_ready"
	WorkUnitClosed         WorkUnitLifecycleState = "closed"

	LineageProjectPolicy   LineageRelation = "project_policy"
	LineageConfirmedIntent LineageRelation = "confirmed_intent"
	LineageChange          LineageRelation = "change"
	LineageWorkSpec        LineageRelation = "work_spec"
	LineageRunSession      LineageRelation = "run_session"
	LineageCommit          LineageRelation = "commit"
	LineagePullRequest     LineageRelation = "pull_request"
	LineageReviewIndex     LineageRelation = "review_index"
	LineageCheckSet        LineageRelation = "check_set"
	LineageTerminalReceipt LineageRelation = "terminal_receipt"
	LineageOwnerDecision   LineageRelation = "owner_decision"
	LineageException       LineageRelation = "exception"
	LineageClosure         LineageRelation = "closure"
)
View Source 
const (
	IntentCanaryV0ManifestID       = CanaryID("intent-canary-v0")
	IntentCanaryV0ManifestVersion  = uint32(1)
	IntentCanaryV0ManifestVersion2 = uint32(2)

	CanaryEligibilityRuleV1      = EvidenceReference("canary-rule:eligibility-v1")
	CanaryCheckRecordingRuleV1   = EvidenceReference("canary-rule:check-recording-v1")
	CanaryAssessmentTimingRuleV1 = EvidenceReference("canary-rule:assessment-timing-v1")
	CanaryMissingDataRuleV1      = EvidenceReference("canary-rule:missing-data-v1")
	CanaryOverheadRuleV1         = EvidenceReference("canary-rule:overhead-v1")
	CanaryRateFormulaRuleV1      = EvidenceReference("canary-rule:rates-v1")

	CanaryAssessmentTimingRuleV2 = EvidenceReference("canary-rule:assessment-timing-v2")
	CanaryMissingDataRuleV2      = EvidenceReference("canary-rule:missing-data-v2")
	CanaryOverheadRuleV2         = EvidenceReference("canary-rule:overhead-v2")
	CanaryContextRuleV2          = EvidenceReference("canary-rule:context-v2")
	CanaryTelemetryRuleV2        = EvidenceReference("canary-rule:telemetry-v2")
	CanaryAssessmentBasisRuleV2  = EvidenceReference("canary-rule:assessment-basis-v2")
)
View Source 
const (
	PolicySchemaV1   = "goalrail.policy/v1"
	MaxPolicyBytes   = 128 << 10
	MaxPolicyRules   = 512
	MaxPolicyActors  = 64
	MaxPolicyPaths   = 256
	MaxPolicyEffects = 64

	PathMatcherExact  PathMatcherKind = "exact"
	PathMatcherPrefix PathMatcherKind = "prefix"

	ChangeAdd       ChangeKind = "add"
	ChangeModify    ChangeKind = "modify"
	ChangeDelete    ChangeKind = "delete"
	ChangeRename    ChangeKind = "rename"
	ChangeMode      ChangeKind = "mode"
	ChangeSubmodule ChangeKind = "submodule"

	MaterialityMaterial    MaterialityClassification = "material"
	MaterialityEvidence    MaterialityClassification = "evidence"
	MaterialityGenerated   MaterialityClassification = "generated"
	MaterialityNonMaterial MaterialityClassification = "non_material"

	ExceptionExempted   ExceptionClass = "exempted"
	ExceptionBreakGlass ExceptionClass = "break_glass"
	ExceptionBootstrap  ExceptionClass = "bootstrap"

	OwnerDecisionAllow  OwnerDecisionOutcome = "allow"
	OwnerDecisionReject OwnerDecisionOutcome = "reject"
)
View Source 
const (
	ProjectSchemaV1                = "goalrail.project/v1"
	BootstrapSchemaV1              = "goalrail.bootstrap/v1"
	ProjectDeclarationPath         = ".goalrail/project.json"
	GovernanceContractV1           = "goalrail-governance-v1"
	DefaultProjectPolicyPath       = ".goalrail/policy.json"
	DefaultProjectBootstrapPath    = ".goalrail/bootstrap.md"
	DefaultProjectSetupProfilePath = ".goalrail/setup-profile.json"
	MaxProjectDeclarationBytes     = 16 << 10
	MaxProjectArtifactPathBytes    = 512
)
View Source 
const (
	SetupProfileSchemaV1      = "goalrail.setup-profile/v1"
	SetupPlanSchemaV1         = "goalrail.setup-plan/v1"
	SetupReceiptSchemaV1      = "goalrail.setup-receipt/v1"
	PlanAuthorizationSchemaV1 = "goalrail.plan-authorization/v1"
	MaxSetupProfileBytes      = 64 << 10
	MaxSetupPlanBytes         = 256 << 10
	MaxSetupReceiptBytes      = 256 << 10
	MaxPlanAuthorizationBytes = 32 << 10
	MaxSetupItems             = 512
	MaxSetupArguments         = 64
	MaxSetupStringBytes       = 2048

	SetupScopeRepository SetupScope = "repository"
	SetupScopeUserLocal  SetupScope = "user_local"

	SetupPlanComplete   SetupPlanState = "complete"
	SetupPlanIncomplete SetupPlanState = "incomplete"

	SetupReceiptSuccess SetupReceiptStatus = "success"
	SetupReceiptFailure SetupReceiptStatus = "failure"
	SetupReceiptRefused SetupReceiptStatus = "refused"
	SetupReceiptNoWrite SetupReceiptStatus = "no_write"

	SetupActionApplied    SetupActionStatus = "applied"
	SetupActionSkipped    SetupActionStatus = "skipped"
	SetupActionFailed     SetupActionStatus = "failed"
	SetupActionRolledBack SetupActionStatus = "rolled_back"

	SetupMutationInstallFile      SetupMutationKind = "install_file"
	SetupMutationEditConfig       SetupMutationKind = "edit_config"
	SetupMutationInstallHook      SetupMutationKind = "install_hook"
	SetupMutationInstallAdapter   SetupMutationKind = "install_adapter"
	SetupMutationSelectExecutable SetupMutationKind = "select_executable"

	SetupPrerequisiteRuntime    SetupPrerequisiteKind = "runtime"
	SetupPrerequisitePlatform   SetupPrerequisiteKind = "platform"
	SetupPrerequisiteFilesystem SetupPrerequisiteKind = "filesystem"
	SetupPrerequisiteTrust      SetupPrerequisiteKind = "trust"
)
View Source 
const (
	WorkSpecSchemaV0 = "goalrail.work-spec/v0"
	WorkSpecSchemaV1 = "goalrail.work-spec/v1"

	PostureTrustedLocalProviderEnforcedV0 WorkSpecPosture = "trusted-local-provider-enforced-v0"
	PostureTrustedLocalProviderEnforcedV1 WorkSpecPosture = "trusted-local-provider-enforced-v1"

	CheckResultPass        CheckResultState = "pass"
	CheckResultFail        CheckResultState = "fail"
	CheckResultUnavailable CheckResultState = "unavailable"
	CheckResultMissing     CheckResultState = "missing"

	MaxWorkSpecBytes       = 64 << 10
	MaxTaskBytes           = 4 << 10
	MaxTextBytes           = 1 << 10
	MaxReferenceBytes      = 512
	MaxPathBytes           = 512
	MaxWorkSpecPaths       = 64
	MaxWorkSpecChecks      = 32
	MaxStopConditions      = 32
	MaxCheckArguments      = 32
	MaxCheckArgumentBytes  = 512
	MaxEvidenceResultBytes = 512
)
View Source 
const EscalationSchema = "goalrail.escalation/v0"

EscalationSchema names the provider-neutral payload shape that downstream tooling validates. Goalrail itself never parses the payload.

View Source 
const MaxEscalationBytes = 64 << 10

MaxEscalationBytes bounds an escalation payload. It is sized for a question rather than for a sentence, so it does not reuse MaxTextBytes.

Variables

View Source 
var (
	ErrInvalidAssessmentBasis = errors.New("invalid canary assessment basis")
	ErrInvalidItemJudgment    = errors.New("invalid intent item judgment")
)
View Source 
var ErrInvalidEscalationPayload = errors.New("invalid escalation payload")
View Source 
var IntentCanaryV0FrozenAt = time.Date(2026, time.July, 21, 13, 17, 33, 0, time.UTC)
View Source 
var IntentCanaryV0FrozenAtV2 = time.Date(2026, time.July, 22, 15, 10, 0, 0, time.UTC)

Functions

func ContainsSecretShapedContent added in v0.2.0 

func ContainsSecretShapedContent(value string) bool

ContainsSecretShapedContent exposes the canonical bounded-payload guard to packages that validate provider-neutral replicas before retaining bytes.

func IsAdmissionReasonCode added in v0.2.0 

func IsAdmissionReasonCode(value AdmissionReasonCode) bool

func IsCanonicalID 

func IsCanonicalID(value string) bool

IsCanonicalID reports whether value is safe to use as a provider-neutral stable identifier in canonical records.

func IsComponentID added in v0.2.1 

func IsComponentID(value string) bool

IsComponentID reports whether value identifies one installed setup component.

It accepts a canonical ID, which is what Goalrail's own components carry, and the namespaced form an ecosystem supplies for the packages inside a bundle. The second is deliberately narrow: one lowercase namespace, then a bounded identity that cannot climb out of anything it is later joined to. This is not IsCanonicalID widened — that rule identifies projects, runs, checks and lineage across the domain, and loosening it there to admit a package path would weaken every one of them.

func IsEvidenceReference 

func IsEvidenceReference(value string) bool

IsEvidenceReference reports whether value is a bounded provider-neutral scheme:identifier reference that is safe to retain.

func IsSHA256Digest added in v0.2.0 

func IsSHA256Digest(value SHA256Digest) bool

IsSHA256Digest reports whether value is a complete lowercase SHA-256 reference rather than a shortened or algorithm-implicit digest.

func ValidateAdmissionPacket added in v0.2.0 

func ValidateAdmissionPacket(value AdmissionPacket) error

func ValidateAdmissionResult added in v0.2.0 

func ValidateAdmissionResult(value AdmissionResult) error

func ValidateAssessmentAgainstBasis 

func ValidateAssessmentAgainstBasis(assessment Assessment, basis CanaryAssessmentBasis) error

ValidateAssessmentAgainstBasis requires one owner judgment for every frozen item and verifies that the aggregate outcome is the deterministic projection of those judgments.

func ValidateCanaryAssessmentBasis 

func ValidateCanaryAssessmentBasis(basis CanaryAssessmentBasis) error

func ValidateCanaryManifest 

func ValidateCanaryManifest(manifest CanaryManifest) error

ValidateCanaryManifest rejects incomplete or changed rules for either known immutable manifest version.

func ValidateContextPack 

func ValidateContextPack(pack ContextPack) error

ValidateContextPack enforces the bounded evidence and stop semantics shared by every collector/provider. It does not decide whether a claim is true.

func ValidateEscalationPayload 

func ValidateEscalationPayload(content []byte) error

ValidateEscalationPayload applies retention hygiene to an escalation payload and nothing else. It deliberately performs no semantic validation: Goalrail runs no checks, and the meaning of the payload belongs to EscalationSchema, which downstream tooling validates.

The rules are the retained-text rules already applied to WorkSpec text, so the two cannot drift into separate families.

func ValidateFlowIntentSnapshot 

func ValidateFlowIntentSnapshot(snapshot IntentSnapshot) error

ValidateFlowIntentSnapshot applies the context gate required by the v2 flow while leaving legacy and baseline Intent Snapshot validation compatible.

func ValidateIntentAmendment 

func ValidateIntentAmendment(previous, next IntentSnapshot, kind AmendmentKind) error

ValidateIntentAmendment checks version linkage and stable semantic identity. The caller classifies meaning as material or wording-only; this function enforces the corresponding lifecycle transition without guessing semantics.

func ValidateIntentSnapshot 

func ValidateIntentSnapshot(snapshot IntentSnapshot) error

ValidateIntentSnapshot checks provider-neutral lifecycle and provenance invariants. It validates structure but never grants effect authority.

func ValidateLineageEvent added in v0.2.0 

func ValidateLineageEvent(value LineageEvent) error

func ValidatePlanAuthorizationReference added in v0.2.0 

func ValidatePlanAuthorizationReference(value PlanAuthorizationReference) error

func ValidateProjectDeclaration added in v0.2.0 

func ValidateProjectDeclaration(declaration ProjectDeclaration) error

func ValidateProjectPolicy added in v0.2.0 

func ValidateProjectPolicy(policy ProjectPolicy) error

func ValidateProposalCoverage 

func ValidateProposalCoverage(intent IntentSnapshot, proposal Proposal) error

ValidateProposalCoverage gates provider-neutral proposal compilation on a confirmed intent and rejects untraced changes, invented intent, or non-goal conflicts. Passing this validation still grants no effect authority.

func ValidateSetupPlan added in v0.2.0 

func ValidateSetupPlan(value SetupPlan) error

func ValidateSetupProfile added in v0.2.0 

func ValidateSetupProfile(value SetupProfile) error

func ValidateSetupReceipt added in v0.2.0 

func ValidateSetupReceipt(value SetupReceipt) error

func ValidateWorkSpec 

func ValidateWorkSpec(spec WorkSpec) error

func ValidateWorkUnit added in v0.2.0 

func ValidateWorkUnit(value WorkUnit) error

Types

type ActorID 

type ActorID string

type AdmissionClassification added in v0.2.0 

type AdmissionClassification string

func ClassifyLegacyWorkSpecBootstrap added in v0.2.0 

func ClassifyLegacyWorkSpecBootstrap(spec WorkSpec, allowedPathPrefixes []string) AdmissionClassification

ClassifyLegacyWorkSpecBootstrap permits legacy authority only for an explicitly bounded set of migration/setup path prefixes. It never returns VALID and does not mutate or upgrade the legacy WorkSpec.

type AdmissionDecision 

type AdmissionDecision string
const (
	AdmissionEligible AdmissionDecision = "eligible"
	AdmissionExcluded AdmissionDecision = "excluded"
)

type AdmissionOutcome added in v0.2.0 

type AdmissionOutcome string

type AdmissionPacket added in v0.2.0 

type AdmissionPacket struct {
	Schema            string                              `json:"schema"`
	ProjectID         ProjectID                           `json:"project_id"`
	DeclarationDigest SHA256Digest                        `json:"declaration_digest"`
	PolicyDigest      SHA256Digest                        `json:"policy_digest"`
	BaseRevision      string                              `json:"base_revision"`
	HeadRevision      string                              `json:"head_revision"`
	WorkUnitRef       ContentAddressedEvidenceReference   `json:"work_unit_ref"`
	EvaluationTime    *time.Time                          `json:"evaluation_time"`
	TimeAuthorityRef  string                              `json:"time_authority_ref"`
	Evidence          []ContentAddressedEvidenceReference `json:"evidence"`
	Provenance        []AdmissionProviderProvenance       `json:"provenance"`
}

func DecodeAdmissionPacket added in v0.2.0 

func DecodeAdmissionPacket(reader io.Reader) (AdmissionPacket, error)

type AdmissionProviderProvenance added in v0.2.0 

type AdmissionProviderProvenance struct {
	AdapterID      string       `json:"adapter_id"`
	ProviderRef    string       `json:"provider_ref"`
	EvidenceDigest SHA256Digest `json:"evidence_digest"`
	ObservedAt     time.Time    `json:"observed_at"`
	Authenticated  bool         `json:"authenticated"`
}

type AdmissionReason added in v0.2.0 

type AdmissionReason struct {
	Code         AdmissionReasonCode `json:"code"`
	EvidenceRefs []string            `json:"evidence_refs"`
}

type AdmissionReasonCode added in v0.2.0 

type AdmissionReasonCode string

func KnownAdmissionReasonCodes added in v0.2.0 

func KnownAdmissionReasonCodes() []AdmissionReasonCode

type AdmissionResult added in v0.2.0 

type AdmissionResult struct {
	Schema          string                            `json:"schema"`
	ProjectID       ProjectID                         `json:"project_id"`
	PolicyDigest    SHA256Digest                      `json:"policy_digest"`
	BaseRevision    string                            `json:"base_revision"`
	HeadRevision    string                            `json:"head_revision"`
	MaterialPaths   []string                          `json:"material_paths"`
	WorkUnitRef     ContentAddressedEvidenceReference `json:"work_unit_ref"`
	Classification  AdmissionClassification           `json:"classification"`
	Outcome         AdmissionOutcome                  `json:"outcome"`
	Reasons         []AdmissionReason                 `json:"reasons"`
	MissingRefs     []string                          `json:"missing_refs"`
	ConflictRefs    []string                          `json:"conflict_refs"`
	VerifierVersion string                            `json:"verifier_version"`
}

func DecodeAdmissionResult added in v0.2.0 

func DecodeAdmissionResult(reader io.Reader) (AdmissionResult, error)

type AmbiguityID 

type AmbiguityID string

type AmendmentKind 

type AmendmentKind string
const (
	AmendmentWordingOnly AmendmentKind = "wording_only"
	AmendmentMaterial    AmendmentKind = "material"
)

type Assessment 

type Assessment struct {
	Outcome                          IntentOutcome        `json:"outcome"`
	AssessedBy                       ActorID              `json:"assessed_by"`
	AssessedAt                       time.Time            `json:"assessed_at"`
	ChecksGreen                      bool                 `json:"checks_green"`
	MaterialCorrectionBeforeDelivery bool                 `json:"material_correction_before_delivery"`
	RepeatOptIn                      *bool                `json:"repeat_opt_in,omitempty"`
	ItemJudgments                    []IntentItemJudgment `json:"item_judgments,omitempty"`
}

Assessment keeps owner intent judgment independent from recorded checks.

type AssessmentBasisTiming 

type AssessmentBasisTiming string
const (
	BasisPreExecution AssessmentBasisTiming = "pre_execution"
	BasisPostDelivery AssessmentBasisTiming = "post_delivery"
)

type CanaryAdmission 

type CanaryAdmission struct {
	Decision  AdmissionDecision `json:"decision"`
	Synthetic bool              `json:"synthetic"`
}

CanaryAdmission records the operator decision before any variant is revealed. An eligible event carries its assignment separately in the same append-only envelope; an exclusion never does.

type CanaryAssessmentBasis 

type CanaryAssessmentBasis struct {
	IntentRef         EvidenceReference     `json:"intent_ref"`
	IntentID          IntentID              `json:"intent_id"`
	IntentVersion     uint32                `json:"intent_version"`
	Timing            AssessmentBasisTiming `json:"timing"`
	DesiredOutcomeIDs []IntentItemID        `json:"desired_outcome_ids"`
	NonGoalIDs        []IntentItemID        `json:"non_goal_ids"`
	SuccessSignalIDs  []IntentItemID        `json:"success_signal_ids"`
}

CanaryAssessmentBasis freezes stable IDs without copying intent wording.

type CanaryAssignment 

type CanaryAssignment struct {
	Ordinal         uint32        `json:"ordinal"`
	Variant         CanaryVariant `json:"variant"`
	ManifestVersion uint32        `json:"manifest_version"`
	IntentVersion   uint32        `json:"intent_version"`
	RunID           RunID         `json:"run_id"`
	Synthetic       bool          `json:"synthetic"`
}

CanaryAssignment freezes ordinal and variant before execution outcome is known. RunID is generated by the launcher and carried in immutable context; no session identity is accepted here.

type CanaryCheckSet 

type CanaryCheckSet struct {
	CheckRefs []EvidenceReference `json:"check_refs"`
}

CanaryCheckSet freezes bounded verification references before terminal verification. Corrections append a new payload and retain every prior ref.

type CanaryContextBinding 

type CanaryContextBinding struct {
	ContextPackID      ContextPackID `json:"context_pack_id"`
	ContextPackVersion uint32        `json:"context_pack_version"`
}

CanaryContextBinding retains only Context Pack identity in runtime evidence.

type CanaryFlowOverhead 

type CanaryFlowOverhead struct {
	AgentTurnCount     uint32  `json:"agent_turn_count"`
	AgentSeconds       float64 `json:"agent_seconds"`
	OwnerReviewSeconds float64 `json:"owner_review_seconds"`
	TotalMinutes       float64 `json:"total_minutes"`
	Available          bool    `json:"available"`
}

CanaryFlowOverhead separates components while exposing one exact total used by the report. Partial components may be present when Available is false, but TotalMinutes is never imputed from incomplete evidence.

func CalculateCanaryFlowOverhead 

func CalculateCanaryFlowOverhead(input CanaryFlowOverheadInput) (CanaryFlowOverhead, error)

CalculateCanaryFlowOverhead implements canary-rule:overhead-v1: sum distinct flow-only root turn envelopes, add the explicit owner-review interval, and divide total seconds by 60 without rounding. Missing required evidence returns Available=false; malformed or duplicate evidence is invalid.

type CanaryFlowOverheadInput 

type CanaryFlowOverheadInput struct {
	AgentTurns          []CanaryTimingInterval `json:"agent_turns"`
	OwnerReview         *CanaryTimingInterval  `json:"owner_review,omitempty"`
	OwnerReviewRequired bool                   `json:"owner_review_required"`
}

type CanaryFlowPhase 

type CanaryFlowPhase struct {
	StartedAt   time.Time `json:"started_at"`
	CompletedAt time.Time `json:"completed_at"`
}

CanaryFlowPhase is the explicit pre-implementation window used for v2 trace selection.

type CanaryHardStopSignals 

type CanaryHardStopSignals struct {
	WrongJoin                  bool `json:"wrong_join"`
	UnresolvedLinks            bool `json:"unresolved_links"`
	EvidenceIntegrityViolation bool `json:"evidence_integrity_violation"`
	ExcessiveOverhead          bool `json:"excessive_overhead"`
	ProcessCausedAbandonments  bool `json:"process_caused_abandonments"`
	TelemetryConflict          bool `json:"telemetry_conflict,omitempty"`
}

type CanaryID 

type CanaryID string

type CanaryLineageOutcome 

type CanaryLineageOutcome string

CanaryLineageOutcome is the canary's assessment of a recorded join. A wrong join is distinct from an explicitly unresolved join because either one wrong association is a hard stop. 

const (
	CanaryLineagePending                   CanaryLineageOutcome = "pending"
	CanaryLineageVerified                  CanaryLineageOutcome = "verified"
	CanaryLineageUnresolvedAfterResolution CanaryLineageOutcome = "unresolved_after_resolution"
	CanaryLineageWrong                     CanaryLineageOutcome = "wrong"
)

type CanaryManifest 

type CanaryManifest struct {
	ID                      CanaryID          `json:"id"`
	Version                 uint32            `json:"version"`
	FrozenAt                time.Time         `json:"frozen_at"`
	AssignmentCount         uint32            `json:"assignment_count"`
	VariantRotation         []CanaryVariant   `json:"variant_rotation"`
	EligibilityRuleRef      EvidenceReference `json:"eligibility_rule_ref"`
	CheckRecordingRuleRef   EvidenceReference `json:"check_recording_rule_ref"`
	AssessmentTimingRuleRef EvidenceReference `json:"assessment_timing_rule_ref"`
	MissingDataRuleRef      EvidenceReference `json:"missing_data_rule_ref"`
	OverheadRuleRef         EvidenceReference `json:"overhead_rule_ref"`
	RateFormulaRuleRef      EvidenceReference `json:"rate_formula_rule_ref"`
	ContextRuleRef          EvidenceReference `json:"context_rule_ref,omitempty"`
	TelemetryRuleRef        EvidenceReference `json:"telemetry_rule_ref,omitempty"`
	AssessmentBasisRuleRef  EvidenceReference `json:"assessment_basis_rule_ref,omitempty"`
}

CanaryManifest identifies the immutable measurement rules frozen before the first assignment. Changing any rule requires a new manifest version.

func NewIntentCanaryV0Manifest 

func NewIntentCanaryV0Manifest() (CanaryManifest, error)

NewIntentCanaryV0Manifest returns the exact v1 manifest frozen for this canary. It does not activate the real-change canary or grant effect authority.

func NewIntentCanaryV0ManifestForVersion 

func NewIntentCanaryV0ManifestForVersion(version uint32) (CanaryManifest, error)

NewIntentCanaryV0ManifestForVersion selects one immutable known manifest.

func NewIntentCanaryV0ManifestV2 

func NewIntentCanaryV0ManifestV2() (CanaryManifest, error)

NewIntentCanaryV0ManifestV2 returns the frozen context-and-evaluation rehearsal contract. Like v1, it is not an activation grant.

type CanaryMeasurement 

type CanaryMeasurement struct {
	Count     uint32  `json:"count"`
	Value     float64 `json:"value"`
	Available bool    `json:"available"`
}

type CanaryObservation 

type CanaryObservation struct {
	Ordinal                           uint32
	ChangeID                          ChangeID
	Variant                           CanaryVariant
	TerminalState                     CanaryTerminalState
	LineageOutcome                    CanaryLineageOutcome
	Assessment                        *Assessment
	MaterialMisunderstandingPrevented bool
	FlowOverheadMinutes               *float64
	ProcessCausedAbandonment          bool
	TelemetryRequired                 bool
	TelemetryStatus                   TelemetryStatus
}

CanaryObservation is one stable assigned change reduced to the facts needed for deterministic reporting. Adapters may derive it from append-only events, but provider-specific trace or workflow types never enter this boundary.

type CanaryPassSignals 

type CanaryPassSignals struct {
	LineageReliable     bool `json:"lineage_reliable"`
	NonMatchRateLower   bool `json:"non_match_rate_lower"`
	PreventionObserved  bool `json:"prevention_observed"`
	OverheadTolerable   bool `json:"overhead_tolerable"`
	RepeatOptInAccepted bool `json:"repeat_opt_in_accepted"`
}

type CanaryRate 

type CanaryRate struct {
	Numerator   uint32  `json:"numerator"`
	Denominator uint32  `json:"denominator"`
	Value       float64 `json:"value"`
	Available   bool    `json:"available"`
}

CanaryRate preserves numerator and denominator so unequal group sizes remain visible. Available is false when the denominator is zero.

type CanaryReport 

type CanaryReport struct {
	Verdict                       CanaryVerdict                 `json:"verdict"`
	AssignmentsStopped            bool                          `json:"assignments_stopped,omitempty"`
	CompletionReady               bool                          `json:"completion_ready"`
	Assigned                      uint32                        `json:"assigned"`
	Excluded                      uint32                        `json:"excluded,omitempty"`
	ExclusionReasons              map[EvidenceReasonCode]uint32 `json:"exclusion_reasons,omitempty"`
	Terminal                      uint32                        `json:"terminal"`
	Flow                          CanaryVariantReport           `json:"flow"`
	Baseline                      CanaryVariantReport           `json:"baseline"`
	LineageVerified               uint32                        `json:"lineage_verified"`
	LineagePending                uint32                        `json:"lineage_pending"`
	LineageUnresolved             uint32                        `json:"lineage_unresolved"`
	WrongJoins                    uint32                        `json:"wrong_joins"`
	TelemetryRequired             uint32                        `json:"telemetry_required,omitempty"`
	TelemetryAvailable            uint32                        `json:"telemetry_available,omitempty"`
	TelemetryUnavailable          uint32                        `json:"telemetry_unavailable,omitempty"`
	TelemetryConflict             uint32                        `json:"telemetry_conflict,omitempty"`
	TelemetryMissing              uint32                        `json:"telemetry_missing,omitempty"`
	ProcessCausedFlowAbandonments uint32                        `json:"process_caused_flow_abandonments"`
	EvidenceIntegrityViolations   uint32                        `json:"evidence_integrity_violations"`
	MedianFlowOverhead            CanaryMeasurement             `json:"median_flow_overhead"`
	PassSignals                   CanaryPassSignals             `json:"pass_signals"`
	HardStopSignals               CanaryHardStopSignals         `json:"hard_stop_signals"`
	NoUsefulMovement              bool                          `json:"no_useful_movement"`
}

func CalculateCanaryReport 

func CalculateCanaryReport(input CanaryReportInput) (CanaryReport, error)

CalculateCanaryReport validates immutable assignment facts, calculates all rates from their actual denominators, and applies hard-stop rules before completion or pass evaluation.

type CanaryReportInput 

type CanaryReportInput struct {
	Observations                []CanaryObservation
	Excluded                    uint32
	ExclusionReasons            map[EvidenceReasonCode]uint32
	EvidenceIntegrityViolations uint32
	AssignmentsStopped          bool
}

type CanaryTelemetry 

type CanaryTelemetry struct {
	Status         TelemetryStatus        `json:"status"`
	SessionLookup  EvidenceReference      `json:"session_lookup"`
	TraceIntervals []CanaryTimingInterval `json:"trace_intervals,omitempty"`
	OwnerReview    *CanaryTimingInterval  `json:"owner_review,omitempty"`
	FlowOverhead   *CanaryFlowOverhead    `json:"flow_overhead,omitempty"`
}

CanaryTelemetry retains only bounded lookup, trace-envelope, and component timing evidence. Detailed provider observations remain in Langfuse.

type CanaryTerminal 

type CanaryTerminal struct {
	State                    CanaryTerminalState `json:"state"`
	CheckRefs                []EvidenceReference `json:"check_refs,omitempty"`
	ChecksGreen              bool                `json:"checks_green"`
	FlowOverheadMinutes      *float64            `json:"flow_overhead_minutes,omitempty"`
	AbandonmentReason        EvidenceReasonCode  `json:"abandonment_reason,omitempty"`
	ProcessCausedAbandonment bool                `json:"process_caused_abandonment,omitempty"`
}

CanaryTerminal records reviewable delivery or explicit abandonment. Check and source details remain bounded references rather than raw output.

type CanaryTerminalState 

type CanaryTerminalState string
const (
	CanaryStatePending   CanaryTerminalState = "pending"
	CanaryStateDelivered CanaryTerminalState = "delivered"
	CanaryStateAbandoned CanaryTerminalState = "abandoned"
)

type CanaryTimingInterval 

type CanaryTimingInterval struct {
	Reference EvidenceReference `json:"reference"`
	StartedAt time.Time         `json:"started_at"`
	EndedAt   time.Time         `json:"ended_at"`
}

CanaryTimingInterval is one source-addressed elapsed interval. Agent turns use one interval per distinct root Codex turn trace; nested observations are deliberately not summed.

type CanaryVariant 

type CanaryVariant string
const (
	VariantFlow     CanaryVariant = "flow"
	VariantBaseline CanaryVariant = "baseline"
)

func CanaryVariantForOrdinal 

func CanaryVariantForOrdinal(ordinal uint32) (CanaryVariant, error)

CanaryVariantForOrdinal deterministically assigns flow, flow, baseline for ordinals 1 through 15. Outcomes and difficulty are deliberately absent.

type CanaryVariantReport 

type CanaryVariantReport struct {
	Assigned                    uint32     `json:"assigned"`
	Pending                     uint32     `json:"pending"`
	Delivered                   uint32     `json:"delivered"`
	Assessed                    uint32     `json:"assessed"`
	MissingAssessments          uint32     `json:"missing_assessments"`
	Abandoned                   uint32     `json:"abandoned"`
	NonMatches                  uint32     `json:"non_matches"`
	WrongButGreen               uint32     `json:"wrong_but_green"`
	MaterialPreventions         uint32     `json:"material_preventions"`
	RepeatOptInYes              uint32     `json:"repeat_opt_in_yes"`
	RepeatOptInNo               uint32     `json:"repeat_opt_in_no"`
	MissingRepeatOptIn          uint32     `json:"missing_repeat_opt_in"`
	OverheadMeasurements        uint32     `json:"overhead_measurements"`
	MissingOverheadMeasurements uint32     `json:"missing_overhead_measurements"`
	NonMatchRate                CanaryRate `json:"non_match_rate"`
}

type CanaryVerdict 

type CanaryVerdict string
const (
	CanaryVerdictPending CanaryVerdict = "PENDING"
	CanaryVerdictPass    CanaryVerdict = "PASS"
	CanaryVerdictStop    CanaryVerdict = "STOP"
	CanaryVerdictReshape CanaryVerdict = "RESHAPE"
)

type CanonicalArtifact added in v0.2.0 

type CanonicalArtifact struct {
	// contains filtered or unexported fields
}

CanonicalArtifact retains deterministic JSON bytes and their content identity. It deliberately carries no mutable decoded value.

func FreezeAdmissionPacket added in v0.2.0 

func FreezeAdmissionPacket(value AdmissionPacket) (CanonicalArtifact, error)

func FreezeAdmissionResult added in v0.2.0 

func FreezeAdmissionResult(value AdmissionResult) (CanonicalArtifact, error)

func FreezeLineageEvent added in v0.2.0 

func FreezeLineageEvent(value LineageEvent) (CanonicalArtifact, error)

func FreezePlanAuthorizationReference added in v0.2.0 

func FreezePlanAuthorizationReference(value PlanAuthorizationReference) (CanonicalArtifact, error)

func FreezeProjectDeclaration added in v0.2.0 

func FreezeProjectDeclaration(declaration ProjectDeclaration) (CanonicalArtifact, error)

func FreezeProjectPolicy added in v0.2.0 

func FreezeProjectPolicy(policy ProjectPolicy) (CanonicalArtifact, error)

func FreezeSetupPlan added in v0.2.0 

func FreezeSetupPlan(value SetupPlan) (CanonicalArtifact, error)

func FreezeSetupProfile added in v0.2.0 

func FreezeSetupProfile(value SetupProfile) (CanonicalArtifact, error)

func FreezeSetupReceipt added in v0.2.0 

func FreezeSetupReceipt(value SetupReceipt) (CanonicalArtifact, error)

func FreezeWorkUnit added in v0.2.0 

func FreezeWorkUnit(value WorkUnit) (CanonicalArtifact, error)

func (CanonicalArtifact) CanonicalJSON added in v0.2.0 

func (artifact CanonicalArtifact) CanonicalJSON() []byte

CanonicalJSON returns a copy of the frozen bytes.

func (CanonicalArtifact) Digest added in v0.2.0 

func (artifact CanonicalArtifact) Digest() SHA256Digest

Digest returns the content identity of CanonicalJSON.

type ChangeID 

type ChangeID string

type ChangeKind added in v0.2.0 

type ChangeKind string

type CheckResultState 

type CheckResultState string

type CommittedArtifactReference added in v0.2.0 

type CommittedArtifactReference struct {
	Schema string       `json:"schema"`
	Path   string       `json:"path"`
	Digest SHA256Digest `json:"digest"`
}

CommittedArtifactReference binds a repository-relative committed path to the exact bytes that govern the project.

type ContentAddressedEvidenceReference added in v0.2.0 

type ContentAddressedEvidenceReference struct {
	ArtifactKind string       `json:"artifact_kind"`
	Identity     string       `json:"identity"`
	Version      string       `json:"version"`
	Digest       SHA256Digest `json:"digest"`
	SourceRef    string       `json:"source_ref"`
	AdapterID    string       `json:"adapter_id"`
}

ContentAddressedEvidenceReference points at exact bounded evidence without copying its semantic body into lineage.

type ContextCollectionOutcome 

type ContextCollectionOutcome string
const (
	ContextSufficient      ContextCollectionOutcome = "sufficient"
	ContextMaterialUnknown ContextCollectionOutcome = "material_unknown"
	ContextBudgetExhausted ContextCollectionOutcome = "budget_exhausted"
)

type ContextItem 

type ContextItem struct {
	ID                 ContextItemID
	Kind               ContextItemKind
	Claim              string
	SourceRef          EvidenceReference
	VerificationRecipe string
	ObservedAt         time.Time
	Relevance          string
}

ContextItem retains one concise fact used to interpret a request. It never becomes owner intent without the owner's separate confirmation.

type ContextItemID 

type ContextItemID string

type ContextItemKind 

type ContextItemKind string
const (
	ContextRepository ContextItemKind = "repository"
	ContextExternal   ContextItemKind = "external"
)

type ContextPack 

type ContextPack struct {
	ID              ContextPackID
	Version         uint32
	PreviousVersion uint32
	StartedAt       time.Time
	CompletedAt     time.Time
	Outcome         ContextCollectionOutcome
	Items           []ContextItem
	Unknowns        []ContextUnknown
}

ContextPack is provider-neutral evidence gathered before flow intent. The outcome records why collection stopped; it is not another intent group.

type ContextPackID 

type ContextPackID string

type ContextUnknown 

type ContextUnknown struct {
	ID         ContextUnknownID
	Question   string
	SourceRefs []EvidenceReference
}

ContextUnknown makes an unresolved material fact explicit instead of allowing the collector to fill it by inference.

type ContextUnknownID 

type ContextUnknownID string

type EvidenceEvent 

type EvidenceEvent struct {
	ID                        EvidenceEventID        `json:"id"`
	CanaryID                  CanaryID               `json:"canary_id"`
	ManifestVersion           uint32                 `json:"manifest_version,omitempty"`
	ChangeID                  ChangeID               `json:"change_id,omitempty"`
	Kind                      EvidenceEventKind      `json:"kind"`
	OccurredAt                time.Time              `json:"occurred_at"`
	Actor                     ActorID                `json:"actor"`
	SourceRef                 EvidenceReference      `json:"source_ref"`
	ObservationRefs           []EvidenceReference    `json:"observation_refs,omitempty"`
	ReasonCode                EvidenceReasonCode     `json:"reason_code,omitempty"`
	SupersedesEventID         EvidenceEventID        `json:"supersedes_event_id,omitempty"`
	Admission                 *CanaryAdmission       `json:"admission,omitempty"`
	Assignment                *CanaryAssignment      `json:"assignment,omitempty"`
	Context                   *CanaryContextBinding  `json:"context,omitempty"`
	AssessmentBasis           *CanaryAssessmentBasis `json:"assessment_basis,omitempty"`
	FlowPhase                 *CanaryFlowPhase       `json:"flow_phase,omitempty"`
	CheckSet                  *CanaryCheckSet        `json:"check_set,omitempty"`
	Lineage                   *ExecutionLineage      `json:"lineage,omitempty"`
	LineageResolutionAttempts uint8                  `json:"lineage_resolution_attempts,omitempty"`
	Terminal                  *CanaryTerminal        `json:"terminal,omitempty"`
	Telemetry                 *CanaryTelemetry       `json:"telemetry,omitempty"`
	Assessment                *Assessment            `json:"assessment,omitempty"`
}

EvidenceEvent is an append-only envelope. SupersedesEventID links a correction without replacing the earlier event.

type EvidenceEventID 

type EvidenceEventID string

type EvidenceEventKind 

type EvidenceEventKind string
const (
	EventAdmissionDecided        EvidenceEventKind = "admission_decided"
	EventChangeStarted           EvidenceEventKind = "change_started"
	EventContextBound            EvidenceEventKind = "context_bound"
	EventAssessmentBasisRecorded EvidenceEventKind = "assessment_basis_recorded"
	EventFlowPhaseRecorded       EvidenceEventKind = "flow_phase_recorded"
	EventCheckSetFrozen          EvidenceEventKind = "check_set_frozen"
	EventLineageRecorded         EvidenceEventKind = "lineage_recorded"
	EventTelemetryRecorded       EvidenceEventKind = "telemetry_recorded"
	EventTerminalStateChanged    EvidenceEventKind = "terminal_state_changed"
	EventAssessmentRecorded      EvidenceEventKind = "assessment_recorded"
	EventMaterialCorrection      EvidenceEventKind = "material_correction"
	EventEvidenceCorrected       EvidenceEventKind = "evidence_corrected"
	EventCanaryStopped           EvidenceEventKind = "canary_stopped"
)

type EvidenceReasonCode 

type EvidenceReasonCode string

type EvidenceReference 

type EvidenceReference string

type ExceptionClass added in v0.2.0 

type ExceptionClass string

type ExecutionLineage 

type ExecutionLineage struct {
	Status             LineageStatus         `json:"status"`
	ChangeID           ChangeID              `json:"change_id"`
	RunID              RunID                 `json:"run_id"`
	RootSessionID      SessionID             `json:"root_session_id,omitempty"`
	IdentitySource     SessionIdentitySource `json:"identity_source,omitempty"`
	ContextDigest      string                `json:"context_digest"`
	UnlinkedReasonCode EvidenceReasonCode    `json:"unlinked_reason_code,omitempty"`
}

ExecutionLineage joins immutable Goalrail run context to provider-authoritative root session identity. Missing or conflicting joins remain explicitly unlinked.

type FrozenWorkSpec 

type FrozenWorkSpec struct {
	// contains filtered or unexported fields
}

FrozenWorkSpec retains canonical bytes and their deterministic identity. Accessors return copies so callers cannot mutate the frozen value in place.

func FreezeWorkSpec 

func FreezeWorkSpec(spec WorkSpec) (FrozenWorkSpec, error)

func OpenFrozenWorkSpec 

func OpenFrozenWorkSpec(canonical []byte, expected WorkSpecDigest) (FrozenWorkSpec, error)

func (FrozenWorkSpec) CanonicalJSON 

func (frozen FrozenWorkSpec) CanonicalJSON() []byte

func (FrozenWorkSpec) Digest 

func (frozen FrozenWorkSpec) Digest() WorkSpecDigest

func (FrozenWorkSpec) Spec 

func (frozen FrozenWorkSpec) Spec() WorkSpec

type IntentAmbiguity 

type IntentAmbiguity struct {
	ID           AmbiguityID
	Question     string
	EvidenceRefs []SourceEvidenceID
}

type IntentConfirmation 

type IntentConfirmation struct {
	Owner              string
	ConfirmedAt        time.Time
	VerificationAction string
}

type IntentDisposition 

type IntentDisposition string
const (
	DispositionAnswered  IntentDisposition = "answered"
	DispositionSpurious  IntentDisposition = "spurious"
	DispositionWithdrawn IntentDisposition = "withdrawn"
)

type IntentEscalationResolution 

type IntentEscalationResolution struct {
	ResolvedID       string
	EscalationDigest string
	Disposition      IntentDisposition
}

IntentEscalationResolution links an answering intent version back to the question it resolves — a blocked run's escalation or a background session's question record, both named by canonical identifier. `spurious` and `withdrawn` exist so a low-value escalation stays visible and countable instead of disappearing.

type IntentID 

type IntentID string

type IntentItem 

type IntentItem struct {
	ID           IntentItemID
	Statement    string
	EvidenceRefs []SourceEvidenceID
	ContextRefs  []ContextItemID
}

IntentItem is one owner-reviewable semantic statement with stable identity.

type IntentItemCategory 

type IntentItemCategory string
const (
	IntentCategoryDesiredOutcome IntentItemCategory = "desired_outcome"
	IntentCategoryNonGoal        IntentItemCategory = "non_goal"
	IntentCategorySuccessSignal  IntentItemCategory = "success_signal"
)

type IntentItemID 

type IntentItemID string

type IntentItemJudgment 

type IntentItemJudgment struct {
	ItemID   IntentItemID            `json:"item_id"`
	Category IntentItemCategory      `json:"category"`
	Judgment IntentItemJudgmentValue `json:"judgment"`
}

type IntentItemJudgmentValue 

type IntentItemJudgmentValue string
const (
	JudgmentAchieved  IntentItemJudgmentValue = "achieved"
	JudgmentPartial   IntentItemJudgmentValue = "partial"
	JudgmentMissed    IntentItemJudgmentValue = "missed"
	JudgmentPreserved IntentItemJudgmentValue = "preserved"
	JudgmentViolated  IntentItemJudgmentValue = "violated"
	JudgmentObserved  IntentItemJudgmentValue = "observed"
	JudgmentMissing   IntentItemJudgmentValue = "missing"
)

type IntentOutcome 

type IntentOutcome string
const (
	IntentMatch   IntentOutcome = "match"
	IntentPartial IntentOutcome = "partial"
	IntentMiss    IntentOutcome = "miss"
)

type IntentSnapshot 

type IntentSnapshot struct {
	ID              IntentID
	Version         uint32
	PreviousVersion uint32
	Status          IntentStatus
	SourceEvidence  []SourceEvidence
	DesiredOutcomes []IntentItem
	NonGoals        []IntentItem
	SuccessSignals  []IntentItem
	Ambiguities     []IntentAmbiguity
	Confirmation    *IntentConfirmation
	ContextPack     *ContextPack

	// ResolvedEscalation records which blocked run this version answers. It is
	// lifecycle provenance rather than a fourth semantic intent group, it is
	// optional, and it grants no effect authority.
	ResolvedEscalation *IntentEscalationResolution
}

IntentSnapshot contains exactly three semantic groups. Provenance and lifecycle data are kept in separate fields and grant no effect authority.

func (IntentSnapshot) GrantsEffectAuthority 

func (IntentSnapshot) GrantsEffectAuthority() bool

GrantsEffectAuthority is deliberately invariant: confirmed intent describes a desired result but never authorizes tools, credentials, writes, or other effects. Effect execution belongs to a separate task-grant boundary.

type IntentStatus 

type IntentStatus string
const (
	IntentCandidate IntentStatus = "candidate"
	IntentConfirmed IntentStatus = "confirmed"
)

type LineageEvent added in v0.2.0 

type LineageEvent struct {
	Schema         string                              `json:"schema"`
	WorkUnitID     WorkUnitID                          `json:"work_unit_id"`
	Relation       LineageRelation                     `json:"relation"`
	Cardinality    RelationCardinality                 `json:"cardinality"`
	Sources        []ContentAddressedEvidenceReference `json:"sources"`
	Targets        []ContentAddressedEvidenceReference `json:"targets"`
	ActorRef       string                              `json:"actor_ref"`
	AdapterID      string                              `json:"adapter_id"`
	ObservedAt     time.Time                           `json:"observed_at"`
	SemanticDigest SHA256Digest                        `json:"semantic_digest"`
}

LineageEvent is an immutable backward-reference event. SemanticDigest identifies the normalized relation payload without hashing itself; the enclosing CanonicalArtifact digest identifies the complete stored bytes.

func DecodeLineageEvent added in v0.2.0 

func DecodeLineageEvent(reader io.Reader) (LineageEvent, error)

type LineageRelation added in v0.2.0 

type LineageRelation string

type LineageRequirement added in v0.2.0 

type LineageRequirement struct {
	Relation    LineageRelation     `json:"relation"`
	Cardinality RelationCardinality `json:"cardinality"`
}

type LineageStatus 

type LineageStatus string
const (
	LineageVerified LineageStatus = "verified"
	LineageUnlinked LineageStatus = "unlinked"
)

type MaterialityClassification added in v0.2.0 

type MaterialityClassification string

type OwnerDecisionOutcome added in v0.2.0 

type OwnerDecisionOutcome string

type PathMatcherKind added in v0.2.0 

type PathMatcherKind string

type PlanAuthorizationReference added in v0.2.0 

type PlanAuthorizationReference struct {
	Schema       string       `json:"schema"`
	ProjectID    ProjectID    `json:"project_id"`
	PlanDigest   SHA256Digest `json:"plan_digest"`
	DecisionRef  string       `json:"decision_ref"`
	ActorRef     string       `json:"actor_ref"`
	AuthorizedAt time.Time    `json:"authorized_at"`
}

func DecodePlanAuthorizationReference added in v0.2.0 

func DecodePlanAuthorizationReference(reader io.Reader) (PlanAuthorizationReference, error)

type PolicyExceptionAuthority added in v0.2.0 

type PolicyExceptionAuthority struct {
	ID                    string         `json:"id"`
	Class                 ExceptionClass `json:"class"`
	ActorRefs             []string       `json:"actor_refs"`
	PathPrefixes          []string       `json:"path_prefixes"`
	EffectScopes          []string       `json:"effect_scopes"`
	MaxDurationSeconds    uint64         `json:"max_duration_seconds"`
	OwnerDecisionRequired bool           `json:"owner_decision_required"`
}

type PolicyOwnerDecision added in v0.2.0 

type PolicyOwnerDecision struct {
	Required      bool                   `json:"required"`
	AuthorityRefs []string               `json:"authority_refs"`
	Outcomes      []OwnerDecisionOutcome `json:"outcomes"`
}

type PolicyPathMatcher added in v0.2.0 

type PolicyPathMatcher struct {
	Kind PathMatcherKind `json:"kind"`
	Path string          `json:"path"`
}

type PolicyPathRule added in v0.2.0 

type PolicyPathRule struct {
	ID                    PolicyRuleID              `json:"id"`
	Matcher               PolicyPathMatcher         `json:"matcher"`
	ChangeKinds           []ChangeKind              `json:"change_kinds"`
	Priority              int                       `json:"priority"`
	Classification        MaterialityClassification `json:"classification"`
	RequiredEvidenceKinds []string                  `json:"required_evidence_kinds"`
}

type PolicyRuleID added in v0.2.0 

type PolicyRuleID string

type ProjectDeclaration added in v0.2.0 

type ProjectDeclaration struct {
	Schema          string                     `json:"schema"`
	ProjectID       ProjectID                  `json:"project_id"`
	ContractVersion string                     `json:"contract_version"`
	Policy          CommittedArtifactReference `json:"policy"`
	Bootstrap       CommittedArtifactReference `json:"bootstrap"`
	// SetupProfile binds both the planning compiler and the prepared shared-
	// admission adapter declared by goalrail.setup-profile/v1.
	SetupProfile CommittedArtifactReference `json:"setup_profile"`
}

ProjectDeclaration is the committed, checkout-independent project identity. It intentionally contains no user, provider, credential, or local readiness fields.

func DecodeProjectDeclaration added in v0.2.0 

func DecodeProjectDeclaration(reader io.Reader) (ProjectDeclaration, error)

type ProjectID added in v0.2.0 

type ProjectID string

func NewProjectID added in v0.2.0 

func NewProjectID() (ProjectID, error)

NewProjectID creates an anonymous project identity from crypto/rand. No machine, user, remote, or checkout identity contributes to the value.

type ProjectPolicy added in v0.2.0 

type ProjectPolicy struct {
	Schema               string                     `json:"schema"`
	ProjectID            ProjectID                  `json:"project_id"`
	Version              uint32                     `json:"version"`
	Rules                []PolicyPathRule           `json:"rules"`
	ExceptionAuthorities []PolicyExceptionAuthority `json:"exception_authorities"`
	OwnerDecision        PolicyOwnerDecision        `json:"owner_decision"`
}

func DecodeProjectPolicy added in v0.2.0 

func DecodeProjectPolicy(reader io.Reader) (ProjectPolicy, error)

type Proposal 

type Proposal struct {
	Changes              []ProposalChange
	PreservedNonGoalRefs []IntentItemID
}

Proposal declares the non-goals preserved by its compiled changes. V0 treats every confirmed non-goal as applicable and requires explicit coverage.

type ProposalChange 

type ProposalChange struct {
	ID                     ProposalChangeID
	Summary                string
	IntentRefs             []IntentItemID
	ConflictingNonGoalRefs []IntentItemID
}

ProposalChange is provider-neutral compiled work traced to confirmed intent.

type ProposalChangeID 

type ProposalChangeID string

type RelationCardinality added in v0.2.0 

type RelationCardinality string

type RunID 

type RunID string

type SHA256Digest added in v0.2.0 

type SHA256Digest string

SHA256Digest is the lowercase, algorithm-qualified identity used by v1 canonical artifacts.

func DigestCanonicalJSON added in v0.2.0 

func DigestCanonicalJSON(content []byte) SHA256Digest

DigestCanonicalJSON returns a lowercase SHA-256 reference for content.

func LineageEventSemanticDigest added in v0.2.0 

func LineageEventSemanticDigest(value LineageEvent) (SHA256Digest, error)

LineageEventSemanticDigest identifies the normalized relation payload with the digest field excluded. This non-self-referential identity is retained in SemanticDigest; the enclosing CanonicalArtifact digest still identifies the complete stored JSON bytes.

type SessionID 

type SessionID string

type SessionIdentitySource 

type SessionIdentitySource string
const (
	SessionIdentityLifecycleHook SessionIdentitySource = "lifecycle_hook"
	SessionIdentityLaunchReceipt SessionIdentitySource = "launch_receipt"
)

type SetupActionStatus added in v0.2.0 

type SetupActionStatus string

type SetupAdapterPin added in v0.2.0 

type SetupAdapterPin struct {
	ID        string       `json:"id"`
	Version   string       `json:"version"`
	SourceRef string       `json:"source_ref"`
	Integrity SHA256Digest `json:"integrity"`
}

type SetupComponent added in v0.2.0 

type SetupComponent struct {
	ID            string       `json:"id"`
	Version       string       `json:"version"`
	SourceRef     string       `json:"source_ref"`
	Integrity     SHA256Digest `json:"integrity"`
	SizeBytes     uint64       `json:"size_bytes"`
	Destination   string       `json:"destination"`
	Scope         SetupScope   `json:"scope"`
	LicenseRef    string       `json:"license_ref"`
	ProvenanceRef string       `json:"provenance_ref"`
}

type SetupComponentResult added in v0.2.0 

type SetupComponentResult struct {
	ID        string            `json:"id"`
	Version   string            `json:"version"`
	Integrity SHA256Digest      `json:"integrity"`
	Status    SetupActionStatus `json:"status"`
}

type SetupMutation added in v0.2.0 

type SetupMutation struct {
	ID                   string            `json:"id"`
	Kind                 SetupMutationKind `json:"kind"`
	Scope                SetupScope        `json:"scope"`
	Path                 string            `json:"path"`
	ExpectedBeforeDigest *SHA256Digest     `json:"expected_before_digest"`
	DesiredDigest        SHA256Digest      `json:"desired_digest"`
}

type SetupMutationKind added in v0.2.0 

type SetupMutationKind string

type SetupMutationResult added in v0.2.0 

type SetupMutationResult struct {
	ID           string            `json:"id"`
	Status       SetupActionStatus `json:"status"`
	BeforeDigest *SHA256Digest     `json:"before_digest"`
	AfterDigest  *SHA256Digest     `json:"after_digest"`
}

type SetupNetworkAccess added in v0.2.0 

type SetupNetworkAccess struct {
	ID        string `json:"id"`
	Method    string `json:"method"`
	URL       string `json:"url"`
	PurposeID string `json:"purpose_id"`
}

type SetupPlan added in v0.2.0 

type SetupPlan struct {
	Schema              string                `json:"schema"`
	ProjectID           ProjectID             `json:"project_id"`
	DeclarationDigest   SHA256Digest          `json:"declaration_digest"`
	SetupProfileDigest  SHA256Digest          `json:"setup_profile_digest"`
	Platform            string                `json:"platform"`
	State               SetupPlanState        `json:"state"`
	IncompleteReasonIDs []string              `json:"incomplete_reason_ids"`
	Components          []SetupComponent      `json:"components"`
	Mutations           []SetupMutation       `json:"mutations"`
	Prerequisites       []SetupPrerequisite   `json:"prerequisites"`
	TrustSteps          []SetupTrustStep      `json:"trust_steps"`
	NetworkAccess       []SetupNetworkAccess  `json:"network_access"`
	Rollback            []SetupRollbackAction `json:"rollback"`
	Verification        []SetupVerification   `json:"verification"`
	ProjectCodeWrites   uint32                `json:"project_code_writes"`
}

func DecodeSetupPlan added in v0.2.0 

func DecodeSetupPlan(reader io.Reader) (SetupPlan, error)

type SetupPlanState added in v0.2.0 

type SetupPlanState string

type SetupPlanningAdapter added in v0.2.0 

type SetupPlanningAdapter struct {
	Adapter         SetupAdapterPin `json:"adapter"`
	Runtime         string          `json:"runtime"`
	RuntimeVersion  string          `json:"runtime_version"`
	Compiler        string          `json:"compiler"`
	CompilerVersion string          `json:"compiler_version"`
}

type SetupPrerequisite added in v0.2.0 

type SetupPrerequisite struct {
	ID                string                `json:"id"`
	Kind              SetupPrerequisiteKind `json:"kind"`
	VersionConstraint string                `json:"version_constraint"`
	Satisfied         bool                  `json:"satisfied"`
	EvidenceRef       string                `json:"evidence_ref"`
}

type SetupPrerequisiteKind added in v0.2.0 

type SetupPrerequisiteKind string

type SetupProfile added in v0.2.0 

type SetupProfile struct {
	Schema                   string               `json:"schema"`
	ProjectID                ProjectID            `json:"project_id"`
	CompatibleGoalrailBundle string               `json:"compatible_goalrail_bundle"`
	Planning                 SetupPlanningAdapter `json:"planning"`
	ScaffoldAdapters         []SetupAdapterPin    `json:"scaffold_adapters"`
	SharedAdmissionAdapter   *SetupAdapterPin     `json:"shared_admission_adapter"`
}

func DecodeSetupProfile added in v0.2.0 

func DecodeSetupProfile(reader io.Reader) (SetupProfile, error)

type SetupReceipt added in v0.2.0 

type SetupReceipt struct {
	Schema          string                      `json:"schema"`
	ProjectID       ProjectID                   `json:"project_id"`
	PlanDigest      SHA256Digest                `json:"plan_digest"`
	Authorization   *PlanAuthorizationReference `json:"authorization"`
	Components      []SetupComponentResult      `json:"components"`
	Mutations       []SetupMutationResult       `json:"mutations"`
	RollbackRef     string                      `json:"rollback_ref"`
	DiagnosisRef    string                      `json:"diagnosis_ref"`
	Status          SetupReceiptStatus          `json:"status"`
	BlockerRefs     []string                    `json:"blocker_refs"`
	ContinuationRef string                      `json:"continuation_ref"`
}

func DecodeSetupReceipt added in v0.2.0 

func DecodeSetupReceipt(reader io.Reader) (SetupReceipt, error)

type SetupReceiptStatus added in v0.2.0 

type SetupReceiptStatus string

type SetupRollbackAction added in v0.2.0 

type SetupRollbackAction struct {
	MutationID       string        `json:"mutation_id"`
	Action           string        `json:"action"`
	Target           string        `json:"target"`
	PriorStateDigest *SHA256Digest `json:"prior_state_digest"`
}

type SetupScope added in v0.2.0 

type SetupScope string

type SetupTrustStep added in v0.2.0 

type SetupTrustStep struct {
	ID          string `json:"id"`
	AdapterID   string `json:"adapter_id"`
	ActionRef   string `json:"action_ref"`
	Interactive bool   `json:"interactive"`
}

type SetupVerification added in v0.2.0 

type SetupVerification struct {
	ID   string   `json:"id"`
	Argv []string `json:"argv"`
}

type SourceEvidence 

type SourceEvidence struct {
	ID        SourceEvidenceID
	Kind      SourceEvidenceKind
	Statement string
	Reference string
}

SourceEvidence preserves what was observed separately from interpretation.

type SourceEvidenceID 

type SourceEvidenceID string

type SourceEvidenceKind 

type SourceEvidenceKind string
const (
	EvidenceOwnerStatement SourceEvidenceKind = "owner_statement"
	EvidenceRepositoryFact SourceEvidenceKind = "repository_fact"
)

type StopConditionID 

type StopConditionID string

type TelemetryStatus 

type TelemetryStatus string
const (
	TelemetryAvailable   TelemetryStatus = "available"
	TelemetryUnavailable TelemetryStatus = "unavailable"
	TelemetryConflict    TelemetryStatus = "conflict"
)

type TraceObservation 

type TraceObservation struct {
	TraceReference EvidenceReference
	SessionID      SessionID
	StartedAt      time.Time
	EndedAt        time.Time
}

TraceObservation is the provider-neutral timing subset returned by a read-only telemetry source. Inputs, outputs, metadata, and credentials do not cross this boundary.

type TraceObservationQuery 

type TraceObservationQuery struct {
	SessionID     SessionID
	FromStartTime time.Time
	ToStartTime   time.Time
}

TraceObservationQuery bounds one exact-session provider read by observation start time. The end is exclusive to match the provider contract.

type ValidationError 

type ValidationError struct {
	Violations []ValidationViolation
}

ValidationError reports every deterministic violation found in one pass.

func (*ValidationError) Error 

func (e *ValidationError) Error() string

type ValidationViolation 

type ValidationViolation struct {
	Code    string
	Path    string
	Message string
}

ValidationViolation is stable machine-readable validation evidence.

type WorkSpec 

type WorkSpec struct {
	Schema         string                     `json:"schema"`
	ID             WorkSpecID                 `json:"id"`
	Version        uint32                     `json:"version"`
	Project        *WorkSpecProjectReference  `json:"project,omitempty"`
	Policy         *WorkSpecPolicyReference   `json:"policy,omitempty"`
	Change         *WorkSpecChangeReference   `json:"change,omitempty"`
	WorkUnit       *WorkSpecWorkUnitReference `json:"work_unit,omitempty"`
	Repository     WorkSpecRepository         `json:"repository"`
	Intent         WorkSpecIntentReference    `json:"intent"`
	Task           string                     `json:"task"`
	Paths          []string                   `json:"paths"`
	Checks         []WorkSpecCheck            `json:"checks"`
	StopConditions []WorkSpecStopCondition    `json:"stop_conditions"`
	Posture        WorkSpecPosture            `json:"posture"`
}

WorkSpec is the complete provider-neutral semantic input for one trusted repository-local run. Provider configuration and session identity are deliberately absent.

func DecodeWorkSpec 

func DecodeWorkSpec(reader io.Reader) (WorkSpec, error)

type WorkSpecChangeReference added in v0.2.0 

type WorkSpecChangeReference struct {
	ID            string       `json:"id"`
	ArtifactRef   string       `json:"artifact_ref"`
	Digest        SHA256Digest `json:"digest"`
	IntentID      IntentID     `json:"intent_id"`
	IntentVersion uint32       `json:"intent_version"`
	IntentDigest  SHA256Digest `json:"intent_digest"`
}

WorkSpecChangeReference identifies the current Goalrail change and records the confirmed intent version that the change was compiled from.

type WorkSpecCheck 

type WorkSpecCheck struct {
	ID   WorkSpecCheckID `json:"id"`
	Argv []string        `json:"argv"`
}

type WorkSpecCheckID 

type WorkSpecCheckID string

type WorkSpecDigest 

type WorkSpecDigest string

type WorkSpecID 

type WorkSpecID string

type WorkSpecIntentReference 

type WorkSpecIntentReference struct {
	ID          IntentID `json:"id"`
	Version     uint32   `json:"version"`
	ArtifactRef string   `json:"artifact_ref"`
	Digest      string   `json:"digest"`
}

type WorkSpecPolicyReference added in v0.2.0 

type WorkSpecPolicyReference struct {
	ArtifactRef string       `json:"artifact_ref"`
	Digest      SHA256Digest `json:"digest"`
}

WorkSpecPolicyReference binds a managed run to the exact committed policy revision used for admission.

type WorkSpecPosture 

type WorkSpecPosture string

type WorkSpecProjectReference added in v0.2.0 

type WorkSpecProjectReference struct {
	ID          ProjectID    `json:"id"`
	ArtifactRef string       `json:"artifact_ref"`
	Digest      SHA256Digest `json:"digest"`
}

WorkSpecProjectReference binds a managed run to the committed project declaration that controls admission for the repository.

type WorkSpecRepository 

type WorkSpecRepository struct {
	Root         string `json:"root"`
	BaseRevision string `json:"base_revision"`
}

type WorkSpecStopCondition 

type WorkSpecStopCondition struct {
	ID          StopConditionID `json:"id"`
	Description string          `json:"description"`
}

type WorkSpecWorkUnitReference added in v0.2.0 

type WorkSpecWorkUnitReference struct {
	ID          WorkUnitID   `json:"id"`
	ArtifactRef string       `json:"artifact_ref"`
	Digest      SHA256Digest `json:"digest"`
}

WorkSpecWorkUnitReference binds the immutable execution authority to one open repository-local work unit.

type WorkUnit added in v0.2.0 

type WorkUnit struct {
	Schema            string                            `json:"schema"`
	ID                WorkUnitID                        `json:"id"`
	ProjectID         ProjectID                         `json:"project_id"`
	DeclarationDigest SHA256Digest                      `json:"declaration_digest"`
	PolicyDigest      SHA256Digest                      `json:"policy_digest"`
	IntentRef         ContentAddressedEvidenceReference `json:"intent_ref"`
	ChangeRef         ContentAddressedEvidenceReference `json:"change_ref"`
	CreatedAt         time.Time                         `json:"created_at"`
	Lifecycle         WorkUnitLifecycleState            `json:"lifecycle"`
	RequiredRelations []LineageRequirement              `json:"required_relations"`
}

func DecodeWorkUnit added in v0.2.0 

func DecodeWorkUnit(reader io.Reader) (WorkUnit, error)

type WorkUnitID added in v0.2.0 

type WorkUnitID string

type WorkUnitLifecycleState added in v0.2.0 

type WorkUnitLifecycleState string

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.