runtime

package
v0.0.7 Latest Latest
Warning

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

 Go to latest Published: Aug 28, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Overview

Package runtime defines Pasture's opaque, version-bounded runtime contracts: the only authority allowed to turn a protocol semantic operation, effect, or typed capability into native runtime behavior for a specific harness at a specific host version.

A RuntimeContract binds exactly one enabled harness (see ir.HarnessID) and a VersionConstraint. It classifies every used orchestration operation, task/process/Git/filesystem effect, and typed capability exactly once as one of effects.RuntimeClass's four members — native, parent-mediated, semantic-instruction, or unsupported — and exposes three separate, opaque-descriptor lookup families:

  • LookupOperationBinding accepts an ir.OperationDescriptor[In, Out];
  • LookupEffectBinding accepts an ir.EffectDescriptor[In, Out];
  • LookupCapabilityBinding accepts an ir.Capability[In, Out].

Every lookup returns (binding, error). Missing, wrong-type, unbound, out-of-range, or unsupported descriptors fail actionably; none collapses into a nil or zero binding. Named string IDs remain descriptor metadata only: an assignable untyped literal is never a lookup operand, because the operand is always a constructor-validated typed descriptor.

External packages contribute a version-bounded binding for an opaque capability descriptor with BindCapability, without editing this package. NewRuntimeContract validates every contribution's codecs, semantics, effect set, and capability-version intersection, requires each requested capability exactly once, and rejects missing, duplicate, or conflicting contributions.

The package also exposes three closed native lifecycle profiles through ClaudeCode2_1_210Lifecycle, Codex0_146_0Lifecycle, and OpenCode1_18_10Lifecycle. Their harness-specific numeric event enums map every pinned native event to observation, gate consultation, or an explicit human response, together with exact transport, blocking, identity, mutation, ordering, reconciliation, failure, and stop-loop behavior. There is no string lookup or registration API. Lifecycle mappings carry generation metadata only: native payloads cannot supply Pasture review/publication authority or create a decision merely because an event occurred. Antigravity fails actionably because no public contract can be pinned; Pi has no adapter profile.

Scope boundary (delivered-surface divergence)

Issue #40 also describes a landing-composition path — the versioned `pasture task integration publish-repository` runtime binding — that threads a MutationContinuation through #43's pure canonicalization/publication preparation and #46's guarded push, and a #49 epoch interaction-mode lowering. Those paths consume task-package APIs (a `task command canonicalize` entry point, a side-effect-free publication preparation, and a `CommitRepositoryPublication` commit) that the ordered #43 base plus #49 policy files do not yet export in internal/tasks. This package therefore delivers the buildable core: the version-bounded contract, the three lookup families, external capability composition, and the initial pinned point contracts. The composite landing binding and the interaction-mode lowering are deferred until their task-side dependencies land as a follow-up change rather than stubbed with a fabricated task surface here.

Index

Constants

This section is empty.

Variables

View Source 
var ErrLifecycleAdapterUnsupported = errors.New("native lifecycle adapter unsupported")

ErrLifecycleAdapterUnsupported identifies a native lifecycle adapter that cannot be generated from a documented, version-bounded host contract.

Functions

func AntigravityLifecycleContract 

func AntigravityLifecycleContract() error

AntigravityLifecycleContract returns the actionable unsupported result for Antigravity generation. No public event catalog or wire contract is available, so returning an error is safer than reserving guessed event names or payloads.

func ComparePrecedence 

func ComparePrecedence(a, b HostVersion) int

ComparePrecedence orders two versions by semantic-version precedence. Build metadata is ignored; a prerelease has lower precedence than the same release. It returns -1, 0, or +1.

Types

type BlockingMode 

type BlockingMode uint8

BlockingMode records whether the native host waits for and can act on this event's result. ConditionallyBlocking is used where the host excludes a documented matcher variant from blocking. 

const (
	NonBlocking BlockingMode = iota + 1
	Blocking
	ConditionallyBlocking
)

func (BlockingMode) IsValid 

func (m BlockingMode) IsValid() bool

func (BlockingMode) String 

func (m BlockingMode) String() string

type CapabilityRuntimeBinding 

type CapabilityRuntimeBinding[In, Out any] interface {
	Class() effects.RuntimeClass
	CapabilityID() ir.CapabilityID
	Version() ir.CapabilityContractVersion
	InputSchema() ir.SchemaID
	OutputSchema() ir.SchemaID
	Semantics() ir.CapabilitySemantics
	Effects() ir.EffectSet
	Native() (NativeCall, bool)
	Mediated() (MediatedLowering, bool)
	Semantic() (SemanticLowering, bool)
	// contains filtered or unexported methods
}

CapabilityRuntimeBinding is the typed binding an external package contributes for one opaque capability descriptor. Its marker method is unexported, so the only values that satisfy it are produced by this package's constructors (NativeCapabilityBinding and its siblings): a foreign implementation carrying a dynamic native name or untyped argument map can never cross the BindCapability boundary.

func LookupCapabilityBinding 

func LookupCapabilityBinding[In, Out any](
	contract RuntimeContract,
	capability ir.Capability[In, Out],
) (CapabilityRuntimeBinding[In, Out], error)

LookupCapabilityBinding resolves the external capability binding contributed for capability. The capability's exact contract version must fall within the contribution's bound range, and its codecs must match the contributed binding.

func MediatedCapabilityBinding 

func MediatedCapabilityBinding[In, Out any](capability ir.Capability[In, Out], lowering MediatedLowering) (CapabilityRuntimeBinding[In, Out], error)

MediatedCapabilityBinding builds a parent-mediated capability binding.

func NativeCapabilityBinding 

func NativeCapabilityBinding[In, Out any](capability ir.Capability[In, Out], call NativeCall) (CapabilityRuntimeBinding[In, Out], error)

NativeCapabilityBinding builds a native capability binding.

func SemanticCapabilityBinding 

func SemanticCapabilityBinding[In, Out any](capability ir.Capability[In, Out], lowering SemanticLowering) (CapabilityRuntimeBinding[In, Out], error)

SemanticCapabilityBinding builds a semantic-instruction capability binding.

type CapabilityVersionRange 

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

CapabilityVersionRange is an inclusive range over ir.CapabilityContractVersion values (MAJOR.MINOR.PATCH). BindCapability uses it to bound which capability contract versions a contribution honors, and to intersect against the requested capability's exact version.

func NewCapabilityVersionRange 

func NewCapabilityVersionRange(min, max ir.CapabilityContractVersion) (CapabilityVersionRange, error)

NewCapabilityVersionRange returns an inclusive [min, max] capability-version range. Both bounds must be well-formed MAJOR.MINOR.PATCH triples and min must not exceed max.

func NewExactCapabilityVersion 

func NewExactCapabilityVersion(version ir.CapabilityContractVersion) (CapabilityVersionRange, error)

NewExactCapabilityVersion returns a range accepting exactly one capability contract version.

func (CapabilityVersionRange) Includes 

func (r CapabilityVersionRange) Includes(version ir.CapabilityContractVersion) bool

Includes reports whether version falls within the inclusive range.

func (CapabilityVersionRange) Intersects 

func (r CapabilityVersionRange) Intersects(other CapabilityVersionRange) bool

Intersects reports whether two ranges overlap.

func (CapabilityVersionRange) IsValid 

func (r CapabilityVersionRange) IsValid() bool

func (CapabilityVersionRange) Max 

func (r CapabilityVersionRange) Max() ir.CapabilityContractVersion

func (CapabilityVersionRange) Min 

func (r CapabilityVersionRange) Min() ir.CapabilityContractVersion

type ClaudeLifecycleEvent 

type ClaudeLifecycleEvent uint8

ClaudeLifecycleEvent is the closed native event catalog for the pinned Claude Code lifecycle profile. Its numeric representation prevents arbitrary native event strings from entering the semantic mapping API. 

const (
	ClaudeEventSessionStart ClaudeLifecycleEvent = iota + 1
	ClaudeEventSetup
	ClaudeEventSessionEnd
	ClaudeEventUserPromptSubmit
	ClaudeEventUserPromptExpansion
	ClaudeEventStop
	ClaudeEventStopFailure
	ClaudeEventPreToolUse
	ClaudeEventPermissionRequest
	ClaudeEventPermissionDenied
	ClaudeEventPostToolUse
	ClaudeEventPostToolUseFailure
	ClaudeEventPostToolBatch
	ClaudeEventFileChanged
	ClaudeEventCwdChanged
	ClaudeEventConfigChange
	ClaudeEventInstructionsLoaded
	ClaudeEventWorktreeCreate
	ClaudeEventWorktreeRemove
	ClaudeEventSubagentStart
	ClaudeEventSubagentStop
	ClaudeEventTeammateIdle
	ClaudeEventTaskCreated
	ClaudeEventTaskCompleted
	ClaudeEventPreCompact
	ClaudeEventPostCompact
	ClaudeEventNotification
	ClaudeEventMessageDisplay
	ClaudeEventElicitation
	ClaudeEventElicitationResult
)

func ClaudeLifecycleEvents 

func ClaudeLifecycleEvents() []ClaudeLifecycleEvent

ClaudeLifecycleEvents returns the deterministic native catalog order used by codegen. The returned slice is a fresh copy.

func (ClaudeLifecycleEvent) IsValid 

func (e ClaudeLifecycleEvent) IsValid() bool

func (ClaudeLifecycleEvent) NativeName 

func (e ClaudeLifecycleEvent) NativeName() string

func (ClaudeLifecycleEvent) String 

func (e ClaudeLifecycleEvent) String() string

type CodexLifecycleEvent 

type CodexLifecycleEvent uint8

CodexLifecycleEvent is the closed native event catalog for the pinned Codex CLI lifecycle profile. 

const (
	CodexEventSessionStart CodexLifecycleEvent = iota + 1
	CodexEventUserPromptSubmit
	CodexEventPreToolUse
	CodexEventPermissionRequest
	CodexEventPostToolUse
	CodexEventPreCompact
	CodexEventPostCompact
	CodexEventSubagentStart
	CodexEventSubagentStop
	CodexEventStop
)

func CodexLifecycleEvents 

func CodexLifecycleEvents() []CodexLifecycleEvent

CodexLifecycleEvents returns the deterministic native catalog order used by codegen. The returned slice is a fresh copy.

func (CodexLifecycleEvent) IsValid 

func (e CodexLifecycleEvent) IsValid() bool

func (CodexLifecycleEvent) NativeName 

func (e CodexLifecycleEvent) NativeName() string

func (CodexLifecycleEvent) String 

func (e CodexLifecycleEvent) String() string

type CoreOperationDescriptor 

type CoreOperationDescriptor = ir.OperationDescriptor[OrchestrationRequest, OrchestrationResult]

CoreOperationDescriptor is the shared typed descriptor kind for every pinned core operation. Every profile classifies exactly this descriptor set, so a caller looks operations up with the same descriptors the contracts registered.

func CoreOperationDescriptorFor 

func CoreOperationDescriptorFor(kind ir.OperationKind) (CoreOperationDescriptor, bool)

CoreOperationDescriptorFor returns the shared descriptor for a core operation kind, so callers look bindings up with the exact descriptor the pinned contracts registered.

type CoreRuntimeBindings 

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

CoreRuntimeBindings is the exhaustive classification of the closed core orchestration vocabulary plus the modeled effects a contract lowers. Every core operation kind (see ir.AllOperationKinds) must be bound exactly once, to exactly one runtime class, so a contract can never be missing a plan for a core operation. Effect descriptors are open-ended and are required only to be unique.

func NewCoreRuntimeBindings 

func NewCoreRuntimeBindings(operations []OperationBinding, effectBindings []EffectBinding) (CoreRuntimeBindings, error)

NewCoreRuntimeBindings validates that operations cover every core operation kind exactly once and that effects are unique, then returns the immutable core binding set.

func (CoreRuntimeBindings) IsValid 

func (b CoreRuntimeBindings) IsValid() bool

type EffectBinding 

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

EffectBinding is the opaque, type-erased binding for one typed effect descriptor, produced by the NativeEffectBinding family.

func MediatedEffectBinding 

func MediatedEffectBinding[In, Out any](descriptor ir.EffectDescriptor[In, Out], lowering MediatedLowering) (EffectBinding, error)

MediatedEffectBinding classifies an effect as parent-mediated.

func NativeEffectBinding 

func NativeEffectBinding[In, Out any](descriptor ir.EffectDescriptor[In, Out], call NativeCall) (EffectBinding, error)

NativeEffectBinding classifies an effect as executed directly by the host.

func SemanticEffectBinding 

func SemanticEffectBinding[In, Out any](descriptor ir.EffectDescriptor[In, Out], lowering SemanticLowering) (EffectBinding, error)

SemanticEffectBinding classifies an effect as a semantic instruction.

func UnsupportedEffectBinding 

func UnsupportedEffectBinding[In, Out any](descriptor ir.EffectDescriptor[In, Out], reason string) (EffectBinding, error)

UnsupportedEffectBinding classifies an effect as unsupported on this contract.

type EventSemantic 

type EventSemantic uint8

EventSemantic is the only Pasture meaning a native lifecycle occurrence may have. A native event never carries Pasture review or publication authority. 

const (
	SemanticObservation EventSemantic = iota + 1
	SemanticGateConsultation
	SemanticExplicitHumanResponse
)

func (EventSemantic) IsValid 

func (s EventSemantic) IsValid() bool

func (EventSemantic) String 

func (s EventSemantic) String() string

type FailureMode 

type FailureMode uint8

FailureMode preserves native process or plugin failure behavior. 

const (
	FailureReportAndContinue FailureMode = iota + 1
	FailureExitTwoBlocks
	FailureStrictHook
	FailureStrictExitTwoBlocks
	FailureThrowFailFast
	FailureObserveOnly
)

func (FailureMode) IsValid 

func (m FailureMode) IsValid() bool

func (FailureMode) String 

func (m FailureMode) String() string

type HandlerOrder 

type HandlerOrder uint8

HandlerOrder preserves native handler scheduling. It does not impose a Pasture ordering or merge rule on concurrent host handlers. 

const (
	OrderConcurrentNative HandlerOrder = iota + 1
	OrderSequentialLoad
	OrderObservationStream
)

func (HandlerOrder) IsValid 

func (o HandlerOrder) IsValid() bool

func (HandlerOrder) String 

func (o HandlerOrder) String() string

type HookSurface 

type HookSurface uint8

HookSurface identifies the exact native transport the generated adapter must implement. It is intentionally closed; codegen cannot register a new surface or select one by string at runtime. 

const (
	SurfaceClaudeCommandJSON HookSurface = iota + 1
	SurfaceCodexStrictCommandJSON
	SurfaceOpenCodeNamedOutput
	SurfaceOpenCodeCatchAllSSE
)

func (HookSurface) IsValid 

func (s HookSurface) IsValid() bool

func (HookSurface) String 

func (s HookSurface) String() string

type HostVersion 

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

HostVersion is a parsed, comparable harness host version. It follows semantic versioning precedence: a release triple MAJOR.MINOR.PATCH, an optional dot-separated prerelease series (which lowers precedence below the same release), and optional build metadata (which never changes precedence). It is opaque and constructor-owned: the only way to produce a non-zero value is ParseHostVersion, so a HostVersion in hand always parsed cleanly and a contract never has to re-parse a raw, possibly-garbage version string.

func ParseHostVersion 

func ParseHostVersion(value string) (HostVersion, error)

ParseHostVersion parses one harness host version. It accepts a leading "v" (so `v2.1.210` and `2.1.210` are the same version), a MAJOR.MINOR.PATCH triple, an optional `-prerelease` series, and optional `+build` metadata. It rejects empty, padded, or otherwise unparsable output actionably rather than letting a garbage string silently compare as some default version.

func (HostVersion) HasPrerelease 

func (v HostVersion) HasPrerelease() bool

HasPrerelease reports whether the version carries a prerelease series, which a constraint must explicitly include before it matches.

func (HostVersion) IsValid 

func (v HostVersion) IsValid() bool

func (HostVersion) String 

func (v HostVersion) String() string

String renders the version in canonical form. Build metadata is preserved for display but never participates in precedence.

type LifecycleContract 

type LifecycleContract[E comparable] struct {
	// contains filtered or unexported fields
}

LifecycleContract is an immutable, exact-version native event table. E is a harness-specific uint enum, so callers cannot look up events by arbitrary string. There is no public constructor or registration API; the only values are the three reviewed static profiles in lifecycle_profiles.go.

func ClaudeCode2_1_210Lifecycle 

func ClaudeCode2_1_210Lifecycle() LifecycleContract[ClaudeLifecycleEvent]

ClaudeCode2_1_210Lifecycle returns the immutable Claude Code lifecycle table bound to the same exact host version and RuntimeContractID as ClaudeCode2_1_210.

func Codex0_146_0Lifecycle 

func Codex0_146_0Lifecycle() LifecycleContract[CodexLifecycleEvent]

Codex0_146_0Lifecycle returns the immutable Codex CLI lifecycle table bound to the same exact host version and RuntimeContractID as Codex0_146_0.

func OpenCode1_18_10Lifecycle 

func OpenCode1_18_10Lifecycle() LifecycleContract[OpenCodeLifecycleEvent]

OpenCode1_18_10Lifecycle returns the immutable OpenCode lifecycle table bound to the same exact host version and RuntimeContractID as OpenCode1_18_10.

func (LifecycleContract[E]) Events 

func (c LifecycleContract[E]) Events() []E

func (LifecycleContract[E]) Harness 

func (c LifecycleContract[E]) Harness() ir.HarnessID

func (LifecycleContract[E]) ID 

func (c LifecycleContract[E]) ID() ir.RuntimeContractID

func (LifecycleContract[E]) IsValid 

func (c LifecycleContract[E]) IsValid() bool

func (LifecycleContract[E]) Mapping 

func (c LifecycleContract[E]) Mapping(event E) (LifecycleEventMapping, error)

Mapping returns immutable generation metadata for one typed native event. Missing or zero event values fail actionably; there is deliberately no string lookup counterpart.

func (LifecycleContract[E]) Supports 

func (c LifecycleContract[E]) Supports(version HostVersion) bool

func (LifecycleContract[E]) Versions 

func (c LifecycleContract[E]) Versions() VersionConstraint

type LifecycleEventMapping 

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

LifecycleEventMapping is immutable generation metadata for one native event. It deliberately contains no native payload and no Pasture command input. In particular, it cannot transport review/publication authority or manufacture a decision from the occurrence of a tool, permission, stop, catch-all, or SSE event.

func (LifecycleEventMapping) Blocking 

func (m LifecycleEventMapping) Blocking() BlockingMode

func (LifecycleEventMapping) DeclaredField 

func (m LifecycleEventMapping) DeclaredField(nativeName string) (NativeIdentityField, bool)

DeclaredField returns the declared native identity field with the exact native name, if the pinned mapping declares one. It is the single lookup used by every lifecycle frontend and by the waist L2 transform, replacing the four private findDeclaredField copies that previously drifted per package.

The match is by exact native spelling: correlation fields are never normalised, so an unpadded, case-sensitive equality is the only correct comparison. The returned NativeIdentityField is a value copy; callers cannot mutate the pinned mapping through it.

func (LifecycleEventMapping) Failure 

func (m LifecycleEventMapping) Failure() FailureMode

func (LifecycleEventMapping) Identities 

func (m LifecycleEventMapping) Identities() []NativeIdentityField

func (LifecycleEventMapping) Mutation 

func (m LifecycleEventMapping) Mutation() MutationMode

func (LifecycleEventMapping) NativeName 

func (m LifecycleEventMapping) NativeName() string

func (LifecycleEventMapping) Order 

func (m LifecycleEventMapping) Order() HandlerOrder

func (LifecycleEventMapping) Reconciliation 

func (m LifecycleEventMapping) Reconciliation() ReconciliationMode

func (LifecycleEventMapping) Semantic 

func (m LifecycleEventMapping) Semantic() EventSemantic

func (LifecycleEventMapping) StopLoop 

func (m LifecycleEventMapping) StopLoop() StopLoopPolicy

func (LifecycleEventMapping) Surface 

func (m LifecycleEventMapping) Surface() HookSurface

func (LifecycleEventMapping) UnresolvedIdentities 

func (m LifecycleEventMapping) UnresolvedIdentities() []NativeIdentityKind

type MediatedLowering 

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

MediatedLowering is the lowering a parent-mediated binding owns: the mediator that executes the effect on the agent's behalf, plus the exact instruction it carries out. A mediated binding proves semantic parity by carrying the descriptor's own preconditions, postconditions, result, and effect set (copied at construction), never a paraphrase.

func NewMediatedLowering 

func NewMediatedLowering(mediator, instruction string) (MediatedLowering, error)

NewMediatedLowering validates and constructs a parent-mediated lowering.

func (MediatedLowering) Instruction 

func (m MediatedLowering) Instruction() string

func (MediatedLowering) IsValid 

func (m MediatedLowering) IsValid() bool

func (MediatedLowering) Mediator 

func (m MediatedLowering) Mediator() string

type MutationMode 

type MutationMode uint8

MutationMode describes the only native payload mutation an adapter may return. Observation and explicit-human mappings always use MutationNone. 

const (
	MutationNone MutationMode = iota + 1
	MutationInput
	MutationOutput
	MutationOutputObject
)

func (MutationMode) IsValid 

func (m MutationMode) IsValid() bool

func (MutationMode) String 

func (m MutationMode) String() string

type NativeCall 

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

NativeCall is the complete native lowering a native binding owns: the exact host call name, its declared argument names, the result/handle semantics, and how the call inherits assignment context. It is opaque and constructor-validated so a native binding can never carry an empty call name or an unnamed result contract.

func NewNativeCall 

func NewNativeCall(callName string, arguments []string, resultSemantics, contextInheritance string) (NativeCall, error)

NewNativeCall validates and constructs a native call lowering. callName and resultSemantics are required; arguments and contextInheritance describe the full request/result dataflow the native fixture must reproduce.

func (NativeCall) Arguments 

func (n NativeCall) Arguments() []string

func (NativeCall) CallName 

func (n NativeCall) CallName() string

func (NativeCall) ContextInheritance 

func (n NativeCall) ContextInheritance() string

func (NativeCall) IsValid 

func (n NativeCall) IsValid() bool

func (NativeCall) ResultSemantics 

func (n NativeCall) ResultSemantics() string

type NativeIdentityField 

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

NativeIdentityField is one native correlation field the generated adapter must forward byte-for-byte. It is opaque and has no public constructor, so a caller cannot add authority-bearing fields to a lifecycle mapping.

func (NativeIdentityField) IsValid 

func (f NativeIdentityField) IsValid() bool

func (NativeIdentityField) Kind 

func (f NativeIdentityField) Kind() NativeIdentityKind

func (NativeIdentityField) NativeName 

func (f NativeIdentityField) NativeName() string

func (NativeIdentityField) Required 

func (f NativeIdentityField) Required() bool

type NativeIdentityKind 

type NativeIdentityKind uint8

NativeIdentityKind identifies correlation data owned by the native harness. These values are not Pasture actors, assignments, decisions, journal IDs, revisions, review evidence, or publication evidence. 

const (
	IdentitySession NativeIdentityKind = iota + 1
	IdentityTurn
	IdentityRequest
	IdentityToolCall
	IdentityAgent
	IdentityMessage
)

func (NativeIdentityKind) IsValid 

func (k NativeIdentityKind) IsValid() bool

func (NativeIdentityKind) String 

func (k NativeIdentityKind) String() string

type OpenCodeLifecycleEvent 

type OpenCodeLifecycleEvent uint8

OpenCodeLifecycleEvent is the closed native named-hook and event-bus catalog for the pinned OpenCode lifecycle profile. 

const (
	OpenCodeEventCommandExecuted OpenCodeLifecycleEvent = iota + 1
	OpenCodeEventFileEdited
	OpenCodeEventFileWatcherUpdated
	OpenCodeEventInstallationUpdated
	OpenCodeEventInstallationUpdateAvailable
	OpenCodeEventLSPClientDiagnostics
	OpenCodeEventLSPUpdated
	OpenCodeEventMessageUpdated
	OpenCodeEventMessageRemoved
	OpenCodeEventMessagePartUpdated
	OpenCodeEventMessagePartRemoved
	OpenCodeEventPermissionUpdated
	OpenCodeEventPermissionReplied
	OpenCodeEventServerConnected
	OpenCodeEventServerInstanceDisposed
	OpenCodeEventSessionCreated
	OpenCodeEventSessionUpdated
	OpenCodeEventSessionDeleted
	OpenCodeEventSessionCompacted
	OpenCodeEventSessionDiff
	OpenCodeEventSessionError
	OpenCodeEventSessionIdle
	OpenCodeEventSessionStatus
	OpenCodeEventTodoUpdated
	OpenCodeEventTUIPromptAppend
	OpenCodeEventTUICommandExecute
	OpenCodeEventTUIToastShow
	OpenCodeEventPTYCreated
	OpenCodeEventPTYUpdated
	OpenCodeEventPTYExited
	OpenCodeEventPTYDeleted
	OpenCodeEventVCSBranchUpdated
	OpenCodeEventChatMessage
	OpenCodeEventChatParams
	OpenCodeEventChatHeaders
	OpenCodeEventPermissionAsk
	OpenCodeEventCommandExecuteBefore
	OpenCodeEventToolExecuteBefore
	OpenCodeEventShellEnv
	OpenCodeEventToolExecuteAfter
	OpenCodeEventExperimentalChatMessagesTransform
	OpenCodeEventExperimentalChatSystemTransform
	OpenCodeEventExperimentalProviderSmallModel
	OpenCodeEventExperimentalSessionCompacting
	OpenCodeEventExperimentalCompactionAutocontinue
	OpenCodeEventExperimentalTextComplete
	OpenCodeEventToolDefinition
)

func OpenCodeLifecycleEvents 

func OpenCodeLifecycleEvents() []OpenCodeLifecycleEvent

OpenCodeLifecycleEvents returns the deterministic native catalog order used by codegen. The returned slice is a fresh copy.

func (OpenCodeLifecycleEvent) IsValid 

func (e OpenCodeLifecycleEvent) IsValid() bool

func (OpenCodeLifecycleEvent) NativeName 

func (e OpenCodeLifecycleEvent) NativeName() string

func (OpenCodeLifecycleEvent) String 

func (e OpenCodeLifecycleEvent) String() string

type OperationBinding 

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

OperationBinding is the opaque, type-erased binding for one semantic operation descriptor, produced by the NativeOperationBinding family and collected by NewCoreRuntimeBindings. It carries the descriptor's identity, codecs, semantics, effects, and its exhaustive runtime classification.

func MediatedOperationBinding 

func MediatedOperationBinding[In, Out any](descriptor ir.OperationDescriptor[In, Out], lowering MediatedLowering) (OperationBinding, error)

MediatedOperationBinding classifies a semantic operation as parent-mediated.

func NativeOperationBinding 

func NativeOperationBinding[In, Out any](descriptor ir.OperationDescriptor[In, Out], call NativeCall) (OperationBinding, error)

NativeOperationBinding classifies a semantic operation as executed directly by the host runtime, owning the complete native call, arguments, result semantics, and context inheritance.

func SemanticOperationBinding 

func SemanticOperationBinding[In, Out any](descriptor ir.OperationDescriptor[In, Out], lowering SemanticLowering) (OperationBinding, error)

SemanticOperationBinding classifies a semantic operation as a semantic-instruction the agent must carry out.

func UnsupportedOperationBinding 

func UnsupportedOperationBinding[In, Out any](descriptor ir.OperationDescriptor[In, Out], reason string) (OperationBinding, error)

UnsupportedOperationBinding classifies a semantic operation as unsupported on this contract. A later lookup fails actionably with reason; it never falls through to a similarly named native call.

type OrchestrationRequest 

type OrchestrationRequest struct {
	Operation string            `json:"operation"`
	Arguments map[string]string `json:"arguments"`
}

OrchestrationRequest is the typed request shape the pinned core operation descriptors carry. It is deliberately simple and JSON-round-trippable so a native binding's fixtures validate a full request shape, not a paraphrase.

type OrchestrationResult 

type OrchestrationResult struct {
	Status  string            `json:"status"`
	Handles map[string]string `json:"handles"`
}

OrchestrationResult is the typed result shape the pinned core operation descriptors carry.

type ReconciliationMode 

type ReconciliationMode uint8

ReconciliationMode specifies who reconciles multiple native handler results. ReconcileNoAdapterMerge is load-bearing for Codex: generated adapters must preserve concurrency without inventing a Pasture merge lattice. 

const (
	ReconcileNone ReconciliationMode = iota + 1
	ReconcileHostNative
	ReconcileNoAdapterMerge
	ReconcileSequentialMutation
)

func (ReconciliationMode) IsValid 

func (m ReconciliationMode) IsValid() bool

func (ReconciliationMode) String 

func (m ReconciliationMode) String() string

type RuntimeBinding 

type RuntimeBinding[In, Out any] interface {

	// Class reports the executable runtime class (never unsupported).
	Class() effects.RuntimeClass
	// DescriptorID returns the descriptor identity string. It is metadata only:
	// it is not a lookup operand and cannot be used to fetch a binding.
	DescriptorID() string
	InputSchema() ir.SchemaID
	OutputSchema() ir.SchemaID
	// Semantics returns the preconditions/postconditions/result the binding
	// proves. For mediated and semantic bindings these are the descriptor's own
	// semantics, copied at construction, not a paraphrase.
	Semantics() ir.DescriptorSemantics
	Effects() ir.EffectSet
	// Native, Mediated, and Semantic expose the class-specific lowering. Exactly
	// one returns ok == true, matching Class.
	Native() (NativeCall, bool)
	Mediated() (MediatedLowering, bool)
	Semantic() (SemanticLowering, bool)
	// contains filtered or unexported methods
}

RuntimeBinding is the typed result of a successful operation or effect lookup. It is always one of the three executable classes — native, parent-mediated, or semantic-instruction; an unsupported classification never yields a binding, it yields an actionable lookup error. The In/Out type parameters are re-attached at lookup time from the descriptor, so a binding value always agrees with the descriptor that produced it.

func LookupEffectBinding 

func LookupEffectBinding[In, Out any](
	contract RuntimeContract,
	descriptor ir.EffectDescriptor[In, Out],
) (RuntimeBinding[In, Out], error)

LookupEffectBinding resolves the runtime binding for a typed effect descriptor with the same guarantees as LookupOperationBinding.

func LookupOperationBinding 

func LookupOperationBinding[In, Out any](
	contract RuntimeContract,
	descriptor ir.OperationDescriptor[In, Out],
) (RuntimeBinding[In, Out], error)

LookupOperationBinding resolves the runtime binding for a semantic operation descriptor. The operand is a constructor-validated typed descriptor, never a raw ID, string, or untyped literal. Missing, invalid, type-incompatible, or unsupported descriptors return an actionable error; none collapses into a nil or zero binding.

type RuntimeBindingContribution 

type RuntimeBindingContribution interface {
	// contains filtered or unexported methods
}

RuntimeBindingContribution is the opaque, heterogeneous contribution BindCapability produces and NewRuntimeContract consumes. Its marker method is unexported so no dynamic native name or untyped argument map can masquerade as a contribution; the only source is BindCapability.

func BindCapability 

func BindCapability[In, Out any](
	capability ir.Capability[In, Out],
	versions CapabilityVersionRange,
	binding CapabilityRuntimeBinding[In, Out],
) (RuntimeBindingContribution, error)

BindCapability contributes a version-bounded runtime binding for one opaque capability descriptor without editing this package. It validates the descriptor's codecs, semantics, and effect set (already enforced by ir.DefineCapability), and the version intersection: the requested capability's exact contract version must fall within versions. The resulting contribution is opaque; NewRuntimeContract validates it further against the full requested-capability set.

type RuntimeContract 

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

RuntimeContract is the opaque, version-bounded profile that lowers protocol semantic operations, effects, and capabilities to native runtime behavior for exactly one harness. The only way to produce a non-zero value is NewRuntimeContract, so a contract in hand has already passed identity, version, exhaustive-core, and contribution validation.

func ClaudeCode2_1_210 

func ClaudeCode2_1_210() RuntimeContract

ClaudeCode2_1_210 is the pinned runtime contract for Claude Code 2.1.210. Its native bindings name only Agent/SendMessage/TaskStop-era tools; it never names a removed team-lifecycle call (TeamCreate/TeamDelete). Any schema or semantic change to this profile requires a new RuntimeContractID.

func Codex0_146_0 

func Codex0_146_0() RuntimeContract

Codex0_146_0 is the pinned runtime contract for Codex 0.146.0. It lowers only the exact exposed collaboration/request-input functions; operations with no exposed Codex function are parent-mediated or lowered as semantic instructions rather than invented.

func NewRuntimeContract 

func NewRuntimeContract(
	id ir.RuntimeContractID,
	harness ir.HarnessID,
	versions VersionConstraint,
	core CoreRuntimeBindings,
	capabilities ...RuntimeBindingContribution,
) (RuntimeContract, error)

NewRuntimeContract validates and constructs a runtime contract. harness must match the harness encoded in id. Each capability contribution is required at most once; duplicate or conflicting contributions fail before construction.

func OpenCode1_18_10 

func OpenCode1_18_10() RuntimeContract

OpenCode1_18_10 is the pinned runtime contract for OpenCode 1.18.10. It uses only OpenCode's documented skill/task/question surfaces. It never invents a persistent-message, follow-up, wait, or close tool: operations with no documented native surface are lowered as semantic instructions, and stopping an assignment is explicitly unsupported rather than a fabricated close call.

func PinnedContracts 

func PinnedContracts() []RuntimeContract

PinnedContracts returns the three initial pinned point contracts, one per enabled harness.

func (RuntimeContract) Harness 

func (c RuntimeContract) Harness() ir.HarnessID

Harness returns the enabled harness this contract lowers for.

func (RuntimeContract) ID 

func (c RuntimeContract) ID() ir.RuntimeContractID

ID returns the contract's version-bounded identity.

func (RuntimeContract) IsValid 

func (c RuntimeContract) IsValid() bool

IsValid reports whether the contract was constructed by NewRuntimeContract.

func (RuntimeContract) Supports 

func (c RuntimeContract) Supports(version HostVersion) bool

Supports reports whether the contract accepts version. An unparsable or zero host version, an out-of-range version, or a prerelease the constraint does not explicitly include is unsupported.

func (RuntimeContract) Versions 

func (c RuntimeContract) Versions() VersionConstraint

Versions returns the version constraint the contract accepts.

type SemanticLowering 

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

SemanticLowering is the lowering a semantic-instruction binding owns: the instruction template the agent must carry out. Like a mediated binding, it proves parity by carrying the descriptor's own semantics and effect set.

func NewSemanticLowering 

func NewSemanticLowering(instructionTemplate string) (SemanticLowering, error)

NewSemanticLowering validates and constructs a semantic-instruction lowering.

func (SemanticLowering) InstructionTemplate 

func (s SemanticLowering) InstructionTemplate() string

func (SemanticLowering) IsValid 

func (s SemanticLowering) IsValid() bool

type StopLoopPolicy 

type StopLoopPolicy uint8

StopLoopPolicy records whether a Stop-family event carries host loop state. ConsultWhenInactive prevents a generated adapter from re-blocking the stop hook invocation that was itself triggered by an earlier block. 

const (
	StopLoopNotApplicable StopLoopPolicy = iota + 1
	StopLoopConsultWhenInactive
)

func (StopLoopPolicy) IsValid 

func (p StopLoopPolicy) IsValid() bool

func (StopLoopPolicy) String 

func (p StopLoopPolicy) String() string

type VersionConstraint 

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

VersionConstraint is a closed, inclusive host-version range [min, max] bounded by semantic-version precedence, plus an explicit prerelease-inclusion policy. A pinned point contract sets min == max. Prereleases are matched only when the constraint explicitly includes them, so an unreleased build never silently satisfies a stable contract.

func NewExactVersion 

func NewExactVersion(version HostVersion) (VersionConstraint, error)

NewExactVersion returns a constraint that accepts exactly one release version. It is the constructor for the initial pinned point ranges.

func NewVersionConstraint 

func NewVersionConstraint(min, max HostVersion, includePrereleases bool) (VersionConstraint, error)

NewVersionConstraint returns an inclusive [min, max] host-version range. includePrereleases governs whether prerelease host versions are eligible at all. min must not exceed max by precedence.

func (VersionConstraint) Allows 

func (c VersionConstraint) Allows(version HostVersion) bool

Allows reports whether version satisfies the constraint. A prerelease host is eligible only when the constraint explicitly includes prereleases; build metadata never changes the decision.

func (VersionConstraint) IncludesPrereleases 

func (c VersionConstraint) IncludesPrereleases() bool

IncludesPrereleases reports the prerelease-inclusion policy.

func (VersionConstraint) IsValid 

func (c VersionConstraint) IsValid() bool

func (VersionConstraint) Max 

func (c VersionConstraint) Max() HostVersion

func (VersionConstraint) Min 

func (c VersionConstraint) Min() HostVersion

Min and Max return the inclusive bounds.

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.