launchapi

package
v0.67.2 Latest Latest
Warning

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

 Go to latest Published: Aug 22, 2026 License: MIT Imports: 17 Imported by: 0

Documentation

Overview

Package launchapi defines AMQ's versioned public launch-intent contract. Runtime plans, roots, leases, bindings, journals, and backend mutation stay owned by internal/launch and are not represented by caller-writable types.

Index

Constants

View Source 
const (
	IntentVersionV1  = 1
	RequestVersionV1 = 1
	ResultVersionV1  = 1
	SubjectSchemaV1  = 1
	SubjectSchemaV2  = 2
)
View Source 
const (
	PrepareOutcomeReady          = "ready"
	PrepareOutcomeActionRequired = "action_required"
	PrepareOutcomeUnsupported    = "unsupported"
)
View Source 
const (
	PlacementCurrentWindow PlacementTargetV1 = "current_window"
	PlacementNewWindow     PlacementTargetV1 = "new_window"
	PlacementSession       PlacementTargetV1 = "session"

	PlacementColumns PlacementLayoutV1 = "columns"
	PlacementRows    PlacementLayoutV1 = "rows"
	PlacementTiled   PlacementLayoutV1 = "tiled"
)
View Source 
const (
	FeatureBaseRoot           = "base_root"
	FeatureOnLive             = "on_live"
	FeatureWrapper            = "wrapper"
	FeaturePlacement          = "placement"
	FeatureInitialInput       = "initial_input"
	FeatureCallerContext      = "caller_context"
	FeatureExecutableIdentity = "executable_identity"
)
View Source 
const ContractSemverV1 = "0.61.1"
View Source 
const MaxInitialInputBytes = 256 * 1024
View Source 
const StrictJSONMaxDepth = 256

StrictJSONMaxDepth bounds the recursive structural scan performed before a public JSON document is decoded into a contract type.

Variables

This section is empty.

Functions

func EncodeResultV1 

func EncodeResultV1(writer io.Writer, result any) error

EncodeResultV1 writes the exact bytes returned by MarshalResultV1.

func MarshalLaunchIntentV1 

func MarshalLaunchIntentV1(intent LaunchIntentV1) ([]byte, error)

func MarshalResultV1 

func MarshalResultV1(result any) ([]byte, error)

MarshalResultV1 is the canonical JSON encoder for all V1 result DTOs.

func ValidateDigest 

func ValidateDigest(digest string) error

Types

type ApplyRequestV1 

type ApplyRequestV1 struct {
	RequestVersion int              `json:"request_version"`
	Prepare        PrepareRequestV1 `json:"prepare"`
	SubjectSchema  int              `json:"subject_schema,omitempty"`
	SubjectDigest  string           `json:"subject_digest"`
	Decisions      []DecisionV1     `json:"decisions"`
}

func DecodeApplyRequestV1 

func DecodeApplyRequestV1(data []byte) (ApplyRequestV1, error)

func (ApplyRequestV1) Validate 

func (request ApplyRequestV1) Validate() error

type ApplyResultV1 

type ApplyResultV1 struct {
	ResultVersion int            `json:"result_version"`
	SubjectSchema int            `json:"subject_schema"`
	Outcome       string         `json:"outcome"`
	ReasonCode    string         `json:"reason_code,omitempty"`
	Hints         []ResultHintV1 `json:"hints,omitempty"`
	// FailureDetail is non-contract diagnostic prose for CLI stderr. It is
	// deliberately excluded from the versioned JSON DTO.
	FailureDetail string `json:"-"`
	// SubjectDigest is the pre-mutation subject that this Apply request was
	// authorized against, not a post-mutation Prepare snapshot.
	SubjectDigest string `json:"subject_digest"`
	PlanDigest    string `json:"plan_digest"`
	TrustDigest   string `json:"trust_digest"`
	// SemanticDigest is a deprecated compatibility alias of TrustDigest.
	SemanticDigest    string                     `json:"semantic_digest"`
	Backend           string                     `json:"backend"`
	Profile           string                     `json:"profile"`
	Disposition       MutationDispositionV1      `json:"disposition"`
	BindingGeneration string                     `json:"binding_generation,omitempty"`
	Roster            RosterDriftV1              `json:"roster"`
	Observations      []ParticipantObservationV1 `json:"observations"`
	Commands          []CommandV1                `json:"commands,omitempty"`
	FollowUps         []RequiredActionV1         `json:"follow_ups,omitempty"`
	Evidence          []EvidenceRefV1            `json:"evidence,omitempty"`
	CallerContext     map[string]string          `json:"caller_context,omitempty"`
}

func Apply 

func Apply(ctx context.Context, request ApplyRequestV1) (ApplyResultV1, error)

Apply revalidates a prior Prepare subject under launch authority, consumes request-local decisions, provisions the participant roster, and runs the existing managed reconciliation crash contract.

type CloseRequestV1 

type CloseRequestV1 = InspectRequestV1

func DecodeCloseRequestV1 

func DecodeCloseRequestV1(data []byte) (CloseRequestV1, error)

type CloseResultV1 

type CloseResultV1 = LifecycleResultV1

func Close 

func Close(ctx context.Context, request CloseRequestV1) (CloseResultV1, error)

type CommandV1 

type CommandV1 struct {
	Argv       []string          `json:"argv"`
	Cwd        string            `json:"cwd"`
	EnvOverlay map[string]string `json:"env_overlay,omitempty"`
}

type CompatibilityV1 

type CompatibilityV1 struct {
	ContractSemver string   `json:"contract_semver"`
	IntentVersions []int    `json:"intent_versions"`
	ResultVersions []int    `json:"result_versions"`
	Features       []string `json:"features"`
}

func Compatibility 

func Compatibility() CompatibilityV1

type ConfigOverrideCapabilityV1 added in v0.64.0 

type ConfigOverrideCapabilityV1 struct {
	Key           string   `json:"key"`
	AllowedValues []string `json:"allowed_values"`
}

type DecisionChoiceV1 

type DecisionChoiceV1 string
const (
	DecisionTrustExactSubject DecisionChoiceV1 = "trust_exact_subject"
	DecisionDeny              DecisionChoiceV1 = "deny"
	DecisionFreshOnce         DecisionChoiceV1 = "fresh_once"
	DecisionAbort             DecisionChoiceV1 = "abort"
	DecisionCloseOld          DecisionChoiceV1 = "close_old"
	DecisionLeaveOld          DecisionChoiceV1 = "leave_old"
	DecisionAcceptDegraded    DecisionChoiceV1 = "accept_degraded"
)

type DecisionV1 

type DecisionV1 struct {
	ActionID string           `json:"action_id"`
	Choice   DecisionChoiceV1 `json:"choice"`
}

type EvidenceRefV1 

type EvidenceRefV1 struct {
	EvidenceVersion int               `json:"evidence_version"`
	ID              string            `json:"id"`
	Kind            string            `json:"kind"`
	SHA256          string            `json:"sha256"`
	ObservedAt      time.Time         `json:"observed_at"`
	CallerContext   map[string]string `json:"caller_context,omitempty"`
}

type ExecutionOptionsV1 

type ExecutionOptionsV1 struct {
	RequireWake  bool           `json:"require_wake"`
	NoGitignore  bool           `json:"no_gitignore"`
	Wake         WakeOptionsV1  `json:"wake"`
	Integrations IntegrationsV1 `json:"integrations,omitempty"`
}

type FocusRequestV1 

type FocusRequestV1 = InspectRequestV1

func DecodeFocusRequestV1 

func DecodeFocusRequestV1(data []byte) (FocusRequestV1, error)

type FocusResultV1 

type FocusResultV1 = LifecycleResultV1

func Focus 

func Focus(ctx context.Context, request FocusRequestV1) (FocusResultV1, error)

type InitialInputErrorCode added in v0.65.3 

type InitialInputErrorCode string
const (
	InitialInputInvalidUTF8 InitialInputErrorCode = "initial_input_invalid_utf8"
	InitialInputControl     InitialInputErrorCode = "initial_input_control"
	InitialInputLeadingDash InitialInputErrorCode = "initial_input_leading_dash"
)

type InitialInputKindV1 added in v0.64.0 

type InitialInputKindV1 string
const (
	InitialInputArgument InitialInputKindV1 = "argument"
	InitialInputStdin    InitialInputKindV1 = "stdin"
	InitialInputFile     InitialInputKindV1 = "file"
)

type InitialInputV1 added in v0.64.0 

type InitialInputV1 struct {
	Kind InitialInputKindV1 `json:"kind"`
	Text string             `json:"text"`
}

type InitialInputValidationError added in v0.65.3 

type InitialInputValidationError struct {
	Code   InitialInputErrorCode
	Detail string
}

InitialInputValidationError is returned before Prepare inspects or mutates any target state when bootstrap text cannot be safely carried as one argv argument.

func (*InitialInputValidationError) Error added in v0.65.3 

func (e *InitialInputValidationError) Error() string

type InjectorMode 

type InjectorMode string
const (
	InjectorAuto  InjectorMode = "auto"
	InjectorRaw   InjectorMode = "raw"
	InjectorPaste InjectorMode = "paste"
	InjectorNone  InjectorMode = "none"
)

type InjectorOptionsV1 

type InjectorOptionsV1 struct {
	Mode InjectorMode `json:"mode"`
	Via  string       `json:"via,omitempty"`
	Args []string     `json:"args,omitempty"`
}

type InspectRequestV1 

type InspectRequestV1 struct {
	RequestVersion int      `json:"request_version"`
	Target         TargetV1 `json:"target"`
}

func DecodeInspectRequestV1 

func DecodeInspectRequestV1(data []byte) (InspectRequestV1, error)

type InspectResultV1 

type InspectResultV1 = LifecycleResultV1

func Inspect 

func Inspect(ctx context.Context, request InspectRequestV1) (InspectResultV1, error)

type IntegrationsV1 

type IntegrationsV1 struct {
	Symphony *SymphonyOptionsV1 `json:"symphony,omitempty"`
}

type LaunchIntentV1 

type LaunchIntentV1 struct {
	IntentVersion int             `json:"intent_version"`
	Participants  []ParticipantV1 `json:"participants"`
}

func DecodeLaunchIntentV1 

func DecodeLaunchIntentV1(data []byte) (LaunchIntentV1, error)

func (*LaunchIntentV1) UnmarshalJSON 

func (intent *LaunchIntentV1) UnmarshalJSON(data []byte) error

func (LaunchIntentV1) Validate 

func (intent LaunchIntentV1) Validate() error

type LifecycleResultV1 

type LifecycleResultV1 struct {
	ResultVersion     int                        `json:"result_version"`
	Outcome           string                     `json:"outcome"`
	ReasonCode        string                     `json:"reason_code,omitempty"`
	Backend           string                     `json:"backend"`
	Profile           string                     `json:"profile"`
	Disposition       MutationDispositionV1      `json:"disposition"`
	BindingGeneration string                     `json:"binding_generation,omitempty"`
	State             string                     `json:"state"`
	Observations      []ParticipantObservationV1 `json:"observations"`
	Evidence          []EvidenceRefV1            `json:"evidence,omitempty"`
	CallerContext     map[string]string          `json:"caller_context,omitempty"`
}

type MutationDispositionV1 added in v0.65.3 

type MutationDispositionV1 string
const (
	MutationDispositionNotAppliedV1 MutationDispositionV1 = "not_applied"
	MutationDispositionCommittedV1  MutationDispositionV1 = "committed"
	MutationDispositionUncertainV1  MutationDispositionV1 = "uncertain"
)

type NegotiatedV1 

type NegotiatedV1 struct {
	ContractSemver string   `json:"contract_semver"`
	IntentVersion  int      `json:"intent_version"`
	ResultVersion  int      `json:"result_version"`
	Features       []string `json:"features"`
}

func Negotiate 

func Negotiate(requirement RequirementV1) (NegotiatedV1, error)

type OnLivePolicyV1 added in v0.64.0 

type OnLivePolicyV1 string
const (
	OnLiveRefuse OnLivePolicyV1 = "refuse"
	OnLiveKeep   OnLivePolicyV1 = "keep"
)

type ParticipantObservationV1 

type ParticipantObservationV1 struct {
	Handle       string `json:"handle"`
	Mailbox      string `json:"mailbox"`
	Runnable     bool   `json:"runnable"`
	Conversation string `json:"conversation"`
	Execution    string `json:"execution"`
	Resource     string `json:"resource"`
	ReasonCode   string `json:"reason_code,omitempty"`
	Disposition  string `json:"disposition,omitempty"`
	StartMode    string `json:"start_mode,omitempty"`
}

type ParticipantPreviewV1 

type ParticipantPreviewV1 struct {
	Handle         string              `json:"handle"`
	Runnable       bool                `json:"runnable"`
	Provider       string              `json:"provider,omitempty"`
	Command        *CommandV1          `json:"command,omitempty"`
	ResumePolicy   ResumePolicy        `json:"resume_policy,omitempty"`
	Execution      *ExecutionOptionsV1 `json:"execution,omitempty"`
	PlannedOutcome string              `json:"planned_outcome"`
}

type ParticipantV1 

type ParticipantV1 struct {
	Handle       string              `json:"handle"`
	Runnable     bool                `json:"runnable"`
	Executable   string              `json:"executable,omitempty"`
	Args         []string            `json:"args,omitempty"`
	Wrapper      *WrapperV1          `json:"wrapper,omitempty"`
	InitialInput *InitialInputV1     `json:"initial_input,omitempty"`
	Cwd          *WorkingDirectoryV1 `json:"cwd,omitempty"`
	EnvOverlay   map[string]string   `json:"env_overlay,omitempty"`
	ResumePolicy ResumePolicy        `json:"resume_policy,omitempty"`
	Execution    *ExecutionOptionsV1 `json:"execution,omitempty"`
	OnLive       OnLivePolicyV1      `json:"on_live,omitempty"`
}

type PlacementLayoutV1 added in v0.64.0 

type PlacementLayoutV1 string

type PlacementPreviewV1 added in v0.64.0 

type PlacementPreviewV1 struct {
	Requested  *PlacementV1 `json:"requested,omitempty"`
	Effective  PlacementV1  `json:"effective"`
	Supported  bool         `json:"supported"`
	ReasonCode string       `json:"reason_code,omitempty"`
}

type PlacementTargetV1 added in v0.64.0 

type PlacementTargetV1 string

type PlacementV1 added in v0.64.0 

type PlacementV1 struct {
	Target       PlacementTargetV1 `json:"target"`
	Layout       PlacementLayoutV1 `json:"layout"`
	StaggerMS    int               `json:"stagger_ms,omitempty"`
	LauncherPane string            `json:"launcher_pane,omitempty"`
}

func (PlacementV1) Validate added in v0.64.0 

func (placement PlacementV1) Validate() error

type PlannedWriteKindV1 added in v0.64.0 

type PlannedWriteKindV1 string
const (
	PlannedWriteCreateBaseRoot PlannedWriteKindV1 = "create_base_root"
	PlannedWriteInitialInput   PlannedWriteKindV1 = "write_initial_input"
)

type PlannedWriteV1 added in v0.64.0 

type PlannedWriteV1 struct {
	WriteID string             `json:"write_id"`
	Kind    PlannedWriteKindV1 `json:"kind"`
	Path    string             `json:"path"`
	Handle  string             `json:"handle,omitempty"`
	SHA256  string             `json:"sha256,omitempty"`
}

type PrepareRequestV1 

type PrepareRequestV1 struct {
	RequestVersion int               `json:"request_version"`
	Target         TargetV1          `json:"target"`
	Launcher       string            `json:"launcher"`
	Placement      *PlacementV1      `json:"placement,omitempty"`
	CallerContext  map[string]string `json:"caller_context,omitempty"`
	Intent         LaunchIntentV1    `json:"intent"`
}

func DecodePrepareRequestV1 

func DecodePrepareRequestV1(data []byte) (PrepareRequestV1, error)

func (PrepareRequestV1) Validate 

func (request PrepareRequestV1) Validate() error

type PrepareResultV1 

type PrepareResultV1 struct {
	ResultVersion   int                        `json:"result_version"`
	SubjectSchema   int                        `json:"subject_schema"`
	Outcome         string                     `json:"outcome"`
	Reason          string                     `json:"reason,omitempty"`
	SubjectDigest   string                     `json:"subject_digest"`
	PlanDigest      string                     `json:"plan_digest"`
	TrustDigest     string                     `json:"trust_digest"`
	PlannedWrites   []PlannedWriteV1           `json:"planned_writes"`
	RequiredActions []RequiredActionV1         `json:"required_actions"`
	Preview         PreviewV1                  `json:"preview"`
	Observations    []ParticipantObservationV1 `json:"observations"`
}

func Prepare 

func Prepare(ctx context.Context, request PrepareRequestV1) (PrepareResultV1, error)

Prepare validates and compiles caller intent, then inspects the exact target without creating or changing filesystem, trust, lease, or backend state.

type PreviewV1 

type PreviewV1 struct {
	Target       TargetV1                 `json:"target"`
	Backend      string                   `json:"backend"`
	Profile      string                   `json:"profile"`
	Participants []ParticipantPreviewV1   `json:"participants"`
	Roster       RosterDriftV1            `json:"roster"`
	Capabilities []ProviderCapabilitiesV1 `json:"capabilities"`
	Placement    *PlacementPreviewV1      `json:"placement,omitempty"`
}

type ProviderCapabilitiesV1 added in v0.64.0 

type ProviderCapabilitiesV1 struct {
	Provider                string                       `json:"provider"`
	GrammarVersion          int                          `json:"grammar_version"`
	VerifiedProviderVersion string                       `json:"verified_provider_version"`
	AllowedArgumentForms    []string                     `json:"allowed_argument_forms"`
	ConfigOverrides         []ConfigOverrideCapabilityV1 `json:"config_overrides"`
	InitialInputKinds       []InitialInputKindV1         `json:"initial_input_kinds"`
}

type RequiredActionKindV1 

type RequiredActionKindV1 string
const (
	RequiredActionTrustConfirmation     RequiredActionKindV1 = "trust_confirmation"
	RequiredActionStaleConversation     RequiredActionKindV1 = "stale_conversation_decision"
	RequiredActionRebindConfirmation    RequiredActionKindV1 = "rebind_confirmation"
	RequiredActionUnsupportedCapability RequiredActionKindV1 = "unsupported_capability_ack"
)

type RequiredActionV1 

type RequiredActionV1 struct {
	ActionID         string               `json:"action_id"`
	Kind             RequiredActionKindV1 `json:"kind"`
	Handles          []string             `json:"handles,omitempty"`
	Resources        []string             `json:"resources,omitempty"`
	AllowedDecisions []DecisionChoiceV1   `json:"allowed_decisions"`
	ReasonCode       string               `json:"reason_code"`
}

type RequirementV1 

type RequirementV1 struct {
	ContractSemver string   `json:"contract_semver"`
	IntentVersion  int      `json:"intent_version"`
	ResultVersion  int      `json:"result_version"`
	Features       []string `json:"features"`
}

type ResultHintV1 added in v0.64.0 

type ResultHintV1 string
const HintReprepareRecommended ResultHintV1 = "reprepare_recommended"

type ResumePolicy 

type ResumePolicy string
const (
	ResumePolicyResume   ResumePolicy = "resume"
	ResumePolicyFresh    ResumePolicy = "fresh"
	ResumePolicyDisabled ResumePolicy = "disabled"
)

type RosterDriftV1 

type RosterDriftV1 struct {
	Desired []string `json:"desired"`
	Present []string `json:"present"`
	Missing []string `json:"missing"`
	Extra   []string `json:"extra"`
}

type StrictJSONError added in v0.65.3 

type StrictJSONError struct {
	Code StrictJSONErrorCode
	Path string
	Key  string
}

StrictJSONError reports a structural JSON error with a stable machine code. Path and Key are retained as structured data so callers do not need to parse the human-readable error string.

func (*StrictJSONError) Error added in v0.65.3 

func (e *StrictJSONError) Error() string

type StrictJSONErrorCode added in v0.65.3 

type StrictJSONErrorCode string

StrictJSONErrorCode identifies a structural error found before decoding a public JSON document into its contract type. 

const (
	StrictJSONDuplicateKey  StrictJSONErrorCode = "duplicate_json_key"
	StrictJSONDepthExceeded StrictJSONErrorCode = "depth_exceeded"
)

type SymphonyEvent 

type SymphonyEvent string
const (
	SymphonyAfterCreate  SymphonyEvent = "after_create"
	SymphonyBeforeRun    SymphonyEvent = "before_run"
	SymphonyAfterRun     SymphonyEvent = "after_run"
	SymphonyBeforeRemove SymphonyEvent = "before_remove"
)

type SymphonyOptionsV1 

type SymphonyOptionsV1 struct {
	Events       []SymphonyEvent `json:"events"`
	WorkspaceKey string          `json:"workspace_key,omitempty"`
}

type TargetV1 

type TargetV1 struct {
	ProjectRoot string `json:"project_root"`
	BaseRoot    string `json:"base_root,omitempty"`
	SessionRoot string `json:"session_root"`
	Session     string `json:"session"`
}

type WakeOptionsV1 

type WakeOptionsV1 struct {
	Mode        WakePolicy         `json:"mode"`
	AuditReason string             `json:"audit_reason,omitempty"`
	Injector    *InjectorOptionsV1 `json:"injector,omitempty"`
}

type WakePolicy 

type WakePolicy string
const (
	WakeEnabled  WakePolicy = "enabled"
	WakeDisabled WakePolicy = "disabled"
)

type WorkingDirectoryKind 

type WorkingDirectoryKind string
const (
	WorkingDirectoryRelative WorkingDirectoryKind = "relative"
	WorkingDirectoryAbsolute WorkingDirectoryKind = "absolute"
)

type WorkingDirectoryV1 

type WorkingDirectoryV1 struct {
	Kind WorkingDirectoryKind `json:"kind"`
	Path string               `json:"path"`
}

type WrapperV1 added in v0.64.0 

type WrapperV1 struct {
	Executable string   `json:"executable"`
	Args       []string `json:"args,omitempty"`
}

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.