packapi

package
v0.1.1 Latest Latest
Warning

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

 Go to latest Published: Jul 14, 2026 License: Apache-2.0 Imports: 19 Imported by: 0

Documentation

Overview

Package packapi defines and compiles AgentAPI Doctor's declarative Scenario and ProtocolPack authoring contracts.

Authored YAML is data, never executable code. Compilation is offline and deterministic: strict YAML and JSON Schema validation, semantic and source linkage checks, fixture resolution, restricted CEL type/cost checking, then RFC 8785 canonical JSON and SHA-256 identity.

Index

Constants

View Source 
const (
	ScenarioAPIVersion = "urn:agentapi-doctor:scenario:v1beta1"
	ScenarioKind       = "Scenario"
	PackAPIVersion     = "urn:agentapi-doctor:pack:v1"
	PackKind           = "ProtocolPack"

	CompilerName                   = "agentapi-doctor-pack-compiler"
	CompilerSemanticVersion        = "0.1.0"
	DefaultMaxCELCost       uint64 = 1000
	AbsoluteMaxCELCost      uint64 = 10000
)
View Source 
const (
	MaxAuthoredYAMLBytes = 4 << 20
)
View Source 
const MaxExpandedTemplateBytes = 1 << 20

Variables

This section is empty.

Functions

func ExpandTemplateString 

func ExpandTemplateString(template string, values map[string]string) (string, error)

ExpandTemplateString performs literal substitution from an explicit value map. It does not evaluate expressions, recurse into replacement values, read environment variables, or access files/network. Compilation must already have admitted each variable through CompileOptions.AllowedVariables.

func IsCompileStage 

func IsCompileStage(err error, stage CompileStage) bool

Types

type AssertStep 

type AssertStep []Assertion

type Assertion 

type Assertion struct {
	Use           string          `json:"use,omitempty"`
	Expression    string          `json:"expression,omitempty"`
	Equals        json.RawMessage `json:"equals,omitempty"`
	AssertionRole AssertionRole   `json:"assertionRole"`
	ObservedAt    string          `json:"observedAt,omitempty"`
	Requirement   string          `json:"requirement,omitempty"`
}

type AssertionRole 

type AssertionRole string
const (
	RolePrecondition    AssertionRole = "precondition"
	RoleNormative       AssertionRole = "normative"
	RoleConsumerProfile AssertionRole = "consumer_profile"
	RoleBehavioral      AssertionRole = "behavioral"
	RoleAdvisory        AssertionRole = "advisory"
)

type ByteSize 

type ByteSize int64

ByteSize is a positive binary byte count authored as a canonical value such as 16MiB. Canonical IR serializes it as an integer. 

const (
	KiB ByteSize = 1 << 10
	MiB ByteSize = 1 << 20
	GiB ByteSize = 1 << 30
)

func (ByteSize) MarshalJSON 

func (size ByteSize) MarshalJSON() ([]byte, error)

func (*ByteSize) UnmarshalJSON 

func (size *ByteSize) UnmarshalJSON(raw []byte) error

func (ByteSize) Validate 

func (size ByteSize) Validate() error

type CELBinding 

type CELBinding struct {
	StepID         string      `json:"step_id"`
	AssertionIndex *int        `json:"assertion_index,omitempty"`
	Purpose        string      `json:"purpose"`
	Compiled       CompiledCEL `json:"compiled"`
}

type CancelStep 

type CancelStep struct {
	Invocation string `json:"invocation"`
	Reason     string `json:"reason"`
}

type CapabilityRequirement 

type CapabilityRequirement struct {
	All  []string `json:"all,omitempty"`
	Any  []string `json:"any,omitempty"`
	None []string `json:"none,omitempty"`
}

type CaptureStep 

type CaptureStep struct {
	Stream string `json:"stream"`
	As     string `json:"as"`
}

type Classification 

type Classification struct {
	Type        ScenarioClass   `json:"type"`
	Stability   Stability       `json:"stability"`
	SideEffects SideEffectClass `json:"sideEffects"`
	Idempotent  *bool           `json:"idempotent"`
}

type CleanupBudget 

type CleanupBudget struct {
	Requests int64                 `json:"requests"`
	Duration publicschema.Duration `json:"duration"`
}

type CompileError 

type CompileError struct {
	Stage CompileStage
	Path  string
	Err   error
}

CompileError identifies the failed deterministic compiler stage.

func (*CompileError) Error 

func (compileError *CompileError) Error() string

func (*CompileError) Unwrap 

func (compileError *CompileError) Unwrap() error

type CompileOptions 

type CompileOptions struct {
	Requirements     map[string]RequirementRecord
	Fixtures         map[string]publicschema.Digest
	AllowedVariables map[string]struct{}
	MaxCELCost       uint64
}

type CompileStage 

type CompileStage string
const (
	StageParse       CompileStage = "parse"
	StageSchema      CompileStage = "schema"
	StageSemantic    CompileStage = "semantic"
	StageRequirement CompileStage = "requirement"
	StageFixture     CompileStage = "fixture"
	StageCEL         CompileStage = "cel"
	StageCanonical   CompileStage = "canonical"
)

type CompiledCEL 

type CompiledCEL struct {
	Source        string `json:"source"`
	EstimatedCost uint64 `json:"estimated_cost"`
}

CompiledCEL records the deterministic, public part of a checked CEL expression. Runtime programs are deliberately not serialized into pack IR.

type CompiledPack 

type CompiledPack struct {
	Authored      ProtocolPack
	IR            PackIR
	CanonicalJSON []byte
	Digest        publicschema.Digest
}

func CompileProtocolPackYAML 

func CompileProtocolPackYAML(raw []byte, options PackCompileOptions) (*CompiledPack, error)

CompileProtocolPackYAML resolves a pack snapshot and scenario selection to exact digests before producing the immutable Pack IR.

type CompiledScenario 

type CompiledScenario struct {
	Authored      Scenario
	IR            ScenarioIR
	CanonicalJSON []byte
	Digest        publicschema.Digest
}

CompiledScenario owns a canonical immutable projection and digest.

func CompileScenarioYAML 

func CompileScenarioYAML(raw []byte, options CompileOptions) (*CompiledScenario, error)

CompileScenarioYAML compiles one authored Scenario without filesystem, network, environment, or credential access. All requirement and fixture facts are supplied explicitly in options.

type CompilerIdentity 

type CompilerIdentity struct {
	Name             string `json:"name"`
	Version          string `json:"version"`
	Canonicalization string `json:"canonicalization"`
	CELEnvironment   string `json:"cel_environment"`
}

type ConformanceSuite 

type ConformanceSuite struct {
	Requirements []string `json:"requirements"`
}

type ControlledBackend 

type ControlledBackend struct {
	Fixture string `json:"fixture"`
}

type EngineCompatibility 

type EngineCompatibility struct {
	MinVersion string `json:"minVersion"`
	MaxMajor   int64  `json:"maxMajor"`
}

type FinalizeStep 

type FinalizeStep struct {
	Finalize string `json:"finalize"`
}

type FixturePin 

type FixturePin struct {
	Ref    string              `json:"ref"`
	Digest publicschema.Digest `json:"digest"`
}

type InvokeStep 

type InvokeStep struct {
	Operation         string             `json:"operation"`
	Driver            string             `json:"driver"`
	ControlledBackend *ControlledBackend `json:"controlledBackend,omitempty"`
	Request           map[string]any     `json:"request"`
}

type PackBudget 

type PackBudget struct {
	MaxRequests int64                 `json:"maxRequests"`
	MaxDuration publicschema.Duration `json:"maxDuration"`
}

type PackCompileOptions 

type PackCompileOptions struct {
	ProtocolSnapshots map[string]publicschema.Digest
	ScenarioFiles     map[string]publicschema.Digest
}

type PackIR 

type PackIR struct {
	SchemaVersion          string              `json:"schema_version"`
	Kind                   string              `json:"kind"`
	Compiler               CompilerIdentity    `json:"compiler"`
	Metadata               PackMetadata        `json:"metadata"`
	Spec                   PackSpecIR          `json:"spec"`
	ProtocolSnapshotDigest publicschema.Digest `json:"protocol_snapshot_digest"`
	ScenarioPins           []ScenarioPin       `json:"scenario_pins"`
}

type PackMetadata 

type PackMetadata struct {
	Name    string `json:"name"`
	Version string `json:"version"`
}

type PackSpec 

type PackSpec struct {
	Engine            EngineCompatibility         `json:"engine"`
	ProtocolSnapshot  ProtocolSnapshotRef         `json:"protocolSnapshot"`
	Scenarios         ScenarioSelection           `json:"scenarios"`
	ConformanceSuites map[string]ConformanceSuite `json:"conformanceSuites"`
	DefaultBudget     PackBudget                  `json:"defaultBudget"`
	Signing           SigningExpectation          `json:"signing,omitempty"`
}

type PackSpecIR 

type PackSpecIR struct {
	Engine            EngineCompatibility         `json:"engine"`
	ProtocolSnapshot  ProtocolSnapshotRef         `json:"protocol_snapshot"`
	Scenarios         ScenarioSelection           `json:"scenarios"`
	ConformanceSuites map[string]ConformanceSuite `json:"conformance_suites"`
	DefaultBudget     PackBudget                  `json:"default_budget"`
}

type ProtocolBinding 

type ProtocolBinding struct {
	Family   string              `json:"family"`
	Snapshot string              `json:"snapshot"`
	Digest   publicschema.Digest `json:"digest"`
}

type ProtocolPack 

type ProtocolPack struct {
	APIVersion string       `json:"apiVersion"`
	Kind       string       `json:"kind"`
	Metadata   PackMetadata `json:"metadata"`
	Spec       PackSpec     `json:"spec"`
}

ProtocolPack is the strict authored pack manifest.

type ProtocolSnapshotRef 

type ProtocolSnapshotRef struct {
	Ref string `json:"ref"`
}

type ProvideToolResultStep 

type ProvideToolResultStep struct {
	CallIDFrom string `json:"callIdFrom"`
	Result     any    `json:"result"`
}

type PublicationPolicy 

type PublicationPolicy struct {
	DataClass string `json:"dataClass"`
}

type RegisterResourceStep 

type RegisterResourceStep struct {
	Resource    string `json:"resource"`
	AcquireFrom string `json:"acquireFrom"`
}

type RepetitionPolicy 

type RepetitionPolicy struct {
	Count  int64  `json:"count,omitempty"`
	Policy string `json:"policy,omitempty"`
}

type ReplayStep 

type ReplayStep struct {
	Fixture string `json:"fixture"`
	As      string `json:"as"`
}

type RequirementLevel 

type RequirementLevel string
const (
	LevelMust   RequirementLevel = "MUST"
	LevelShould RequirementLevel = "SHOULD"
	LevelMay    RequirementLevel = "MAY"
)
type RequirementLink struct {
	ID           string              `json:"id"`
	Level        RequirementLevel    `json:"level"`
	Category     ScenarioClass       `json:"category"`
	SourceDigest publicschema.Digest `json:"source_digest"`
}

type RequirementRecord 

type RequirementRecord struct {
	ID           string
	Level        RequirementLevel
	SourceDigest publicschema.Digest
	Category     ScenarioClass
}

RequirementRecord is the immutable catalog fact supplied to the compiler. The compiler does not fetch sources or infer requirements.

type RequirementRef 

type RequirementRef struct {
	ID    string           `json:"id"`
	Level RequirementLevel `json:"level"`
}

type ResourceFinalizer 

type ResourceFinalizer struct {
	Operation  string      `json:"operation"`
	Idempotent *bool       `json:"idempotent"`
	Retry      RetryPolicy `json:"retry"`
}

type ResourceLease 

type ResourceLease struct {
	ID              string            `json:"id"`
	AcquireFrom     string            `json:"acquireFrom"`
	SideEffectClass SideEffectClass   `json:"sideEffectClass"`
	Finalizer       ResourceFinalizer `json:"finalizer"`
	CleanupBudget   CleanupBudget     `json:"cleanupBudget"`
}

type RetryPolicy 

type RetryPolicy struct {
	MaxAttempts int64 `json:"maxAttempts"`
}

type Scenario 

type Scenario struct {
	APIVersion string           `json:"apiVersion"`
	Kind       string           `json:"kind"`
	Metadata   ScenarioMetadata `json:"metadata"`
	Spec       ScenarioSpec     `json:"spec"`
}

Scenario is the strict authored YAML form.

type ScenarioBudget 

type ScenarioBudget struct {
	Timeout          publicschema.Duration `json:"timeout"`
	MaxRequests      int64                 `json:"maxRequests"`
	MaxInputTokens   int64                 `json:"maxInputTokens"`
	MaxOutputTokens  int64                 `json:"maxOutputTokens"`
	MaxResponseBytes ByteSize              `json:"maxResponseBytes,omitempty"`
	MaxArtifactBytes ByteSize              `json:"maxArtifactBytes"`
}

type ScenarioClass 

type ScenarioClass string
const (
	ClassNormative       ScenarioClass = "normative"
	ClassDeFactoClient   ScenarioClass = "de-facto-client"
	ClassConsumerProfile ScenarioClass = "consumer-profile"
	ClassBehavioral      ScenarioClass = "behavioral"
	ClassAdvisory        ScenarioClass = "advisory"
)

type ScenarioIR 

type ScenarioIR struct {
	SchemaVersion    string            `json:"schema_version"`
	Kind             string            `json:"kind"`
	Compiler         CompilerIdentity  `json:"compiler"`
	Scenario         Scenario          `json:"scenario"`
	RequirementLinks []RequirementLink `json:"requirement_links"`
	FixturePins      []FixturePin      `json:"fixture_pins"`
	CELBindings      []CELBinding      `json:"cel_bindings,omitempty"`
	TemplateBindings []TemplateBinding `json:"template_bindings,omitempty"`
}

ScenarioIR is the canonical compiler output. It contains no YAML syntax, source comments, unresolved fixtures, or executable program objects.

type ScenarioMetadata 

type ScenarioMetadata struct {
	ID      string            `json:"id"`
	Version string            `json:"version"`
	Title   string            `json:"title"`
	Labels  map[string]string `json:"labels,omitempty"`
}

type ScenarioPin 

type ScenarioPin struct {
	Path   string              `json:"path"`
	Digest publicschema.Digest `json:"digest"`
}

type ScenarioSelection 

type ScenarioSelection struct {
	Include []string `json:"include"`
}

type ScenarioSpec 

type ScenarioSpec struct {
	Protocol       ProtocolBinding       `json:"protocol"`
	Classification Classification        `json:"classification"`
	Requirements   []RequirementRef      `json:"requirements"`
	Requires       CapabilityRequirement `json:"requires,omitempty"`
	Budgets        ScenarioBudget        `json:"budgets"`
	Steps          []Step                `json:"steps"`
	Resources      []ResourceLease       `json:"resources,omitempty"`
	Finally        []FinalizeStep        `json:"finally,omitempty"`
	Repetition     RepetitionPolicy      `json:"repetition,omitempty"`
	Publication    PublicationPolicy     `json:"publication"`
}

type SideEffectClass 

type SideEffectClass string
const (
	SideEffectNone             SideEffectClass = "none"
	SideEffectReversibleLocal  SideEffectClass = "reversible-local"
	SideEffectReversibleRemote SideEffectClass = "reversible-remote"
	SideEffectIrreversible     SideEffectClass = "irreversible"
)

type SigningExpectation 

type SigningExpectation struct {
	Digest publicschema.Digest `json:"digest,omitempty"`
}

type Stability 

type Stability string
const (
	StabilityStable       Stability = "stable"
	StabilityExperimental Stability = "experimental"
	StabilityIncubating   Stability = "incubating"
)

type Step 

type Step struct {
	ID                string                 `json:"id"`
	Invoke            *InvokeStep            `json:"invoke,omitempty"`
	Capture           *CaptureStep           `json:"capture,omitempty"`
	RegisterResource  *RegisterResourceStep  `json:"register_resource,omitempty"`
	ProvideToolResult *ProvideToolResultStep `json:"provide_tool_result,omitempty"`
	WaitFor           *WaitForStep           `json:"wait_for,omitempty"`
	Assert            *AssertStep            `json:"assert,omitempty"`
	Cancel            *CancelStep            `json:"cancel,omitempty"`
	Replay            *ReplayStep            `json:"replay,omitempty"`
	Finalize          *FinalizeStep          `json:"finalize,omitempty"`
}

Step is a tagged union. Exactly one of the nine operation fields is legal.

type TemplateBinding 

type TemplateBinding struct {
	Path      string   `json:"path"`
	Variables []string `json:"variables"`
}

TemplateBinding is a prevalidated runtime substitution site. Expansion may only use the listed variables supplied by the resolved plan; no expression, environment, file, or command evaluation is involved.

type WaitForStep 

type WaitForStep struct {
	Source    string                `json:"source"`
	Condition string                `json:"condition"`
	Timeout   publicschema.Duration `json:"timeout"`
}

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.