capability

package
v0.6.20 Latest Latest
Warning

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

 Go to latest Published: Jul 27, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Index

Constants

View Source 
const ResponseRedactedValue = "[REDACTED]"

ResponseRedactedValue is the only wire value used to replace sensitive response data.

View Source 
const RiskPlanSchemaVersion = "redevplugin.capability.risk_plan.v1"

Variables

View Source 
var (
	ErrInvalidRegistration     = errors.New("capability registration is invalid")
	ErrRegistrationMissing     = errors.New("capability registration is missing")
	ErrInvalidExecutionBinding = errors.New("capability execution binding is invalid")
	ErrExecutionRevoked        = errors.New("capability execution is revoked")
	ErrInvalidExecutionFailure = errors.New("capability execution failure is invalid")
	ErrQuotaExceeded           = errors.New("capability execution quota exceeded")
)
View Source 
var ErrInvalidRiskPlan = errors.New("invalid capability risk plan")

Functions

func NormalizeRiskPlanData 

func NormalizeRiskPlanData(data any) (any, error)

func PrepareResponseData added in v0.5.0 

func PrepareResponseData(data any) (any, error)

PrepareResponseData creates and redacts the bounded JSON value that may leave an adapter boundary.

func ValidateExecutionBinding added in v0.5.0 

func ValidateExecutionBinding(binding ExecutionBinding) error

ValidateExecutionBinding validates the closed cross-language execution snapshot without invoking JSON marshalers or changing container ownership.

Types

type Adapter 

type Adapter interface {
	Invoke(ctx context.Context, req Invocation) (Result, error)
}

type BusinessError added in v0.3.0 

type BusinessError struct {
	CapabilityID       string         `json:"capability_id,omitempty"`
	CapabilityVersion  string         `json:"capability_version,omitempty"`
	DetailSchemaSHA256 string         `json:"detail_schema_sha256,omitempty"`
	Code               string         `json:"code"`
	Message            string         `json:"message"`
	Details            map[string]any `json:"details,omitempty"`
}

func NewBusinessError added in v0.3.0 

func NewBusinessError(code, message string, details map[string]any) (*BusinessError, error)

NewBusinessError validates details against the closed canonical JSON set and retains a recursively cloned value. Callers may mutate their input after the function returns. Integers must be represented as safe json.Number or float64 values because native integer types are outside the cross-language execution contract.

func (*BusinessError) Error added in v0.3.0 

func (e *BusinessError) Error() string

type ConfirmationEvidence added in v0.3.0 

type ConfirmationEvidence struct {
	Required       bool   `json:"required"`
	Confirmed      bool   `json:"confirmed"`
	ConfirmationID string `json:"confirmation_id,omitempty"`
	RequestSHA256  string `json:"request_sha256,omitempty"`
	PlanSHA256     string `json:"plan_sha256,omitempty"`
	TargetSHA256   string `json:"target_sha256,omitempty"`
}

type Effect 

type Effect string
const (
	EffectRead    Effect = "read"
	EffectWrite   Effect = "write"
	EffectExecute Effect = "execute"
	EffectDelete  Effect = "delete"
	EffectAdmin   Effect = "admin"
)

type ExecutionBinding added in v0.3.0 

type ExecutionBinding struct {
	InvocationID            string                  `json:"invocation_id"`
	AuditCorrelationID      string                  `json:"audit_correlation_id"`
	OperationID             string                  `json:"operation_id,omitempty"`
	StreamID                string                  `json:"stream_id,omitempty"`
	PublisherID             string                  `json:"publisher_id"`
	PluginID                string                  `json:"plugin_id"`
	PluginInstanceID        string                  `json:"plugin_instance_id"`
	PluginVersion           string                  `json:"plugin_version"`
	ActiveFingerprint       string                  `json:"active_fingerprint"`
	SurfaceInstanceID       string                  `json:"surface_instance_id,omitempty"`
	OwnerSessionHash        string                  `json:"owner_session_hash,omitempty"`
	OwnerUserHash           string                  `json:"owner_user_hash,omitempty"`
	OwnerEnvHash            string                  `json:"owner_env_hash,omitempty"`
	SessionChannelIDHash    string                  `json:"session_channel_id_hash,omitempty"`
	BridgeChannelID         string                  `json:"bridge_channel_id,omitempty"`
	RouteKind               RouteKind               `json:"route_kind"`
	CapabilityID            string                  `json:"capability_id"`
	CapabilityVersion       string                  `json:"capability_version"`
	BindingID               string                  `json:"binding_id"`
	Contract                *capabilitycontract.Pin `json:"contract,omitempty"`
	Method                  string                  `json:"method"`
	TargetMethod            string                  `json:"target_method"`
	Effect                  Effect                  `json:"effect"`
	Execution               string                  `json:"execution"`
	Permissions             PermissionEvidence      `json:"permissions"`
	Confirmation            ConfirmationEvidence    `json:"confirmation"`
	Revision                RevisionEvidence        `json:"revision"`
	Quota                   QuotaGrant              `json:"quota"`
	Target                  TargetDescriptor        `json:"target"`
	TargetDescriptorSHA256  string                  `json:"target_descriptor_sha256"`
	StreamEventTypeName     string                  `json:"stream_event_type_name,omitempty"`
	StreamEventSchemaSHA256 string                  `json:"stream_event_schema_sha256,omitempty"`
}

func CloneExecutionBinding added in v0.3.0 

func CloneExecutionBinding(binding ExecutionBinding) (ExecutionBinding, error)

CloneExecutionBinding returns an independently owned execution snapshot.

func (ExecutionBinding) Identity added in v0.3.0 

func (b ExecutionBinding) Identity() PluginIdentity

func (ExecutionBinding) OwnerScope added in v0.5.0 

func (b ExecutionBinding) OwnerScope() ExecutionOwnerScope

func (ExecutionBinding) Surface added in v0.3.0 

func (b ExecutionBinding) Surface() SurfaceScope

type ExecutionContext added in v0.3.0 

type ExecutionContext struct {
	ExecutionBinding
	Operation OperationSink `json:"-"`
	Stream    StreamSink    `json:"-"`
}

type ExecutionFailureCode added in v0.5.0 

type ExecutionFailureCode string
const (
	ExecutionFailureAdapterFailed   ExecutionFailureCode = "adapter_failed"
	ExecutionFailureContractInvalid ExecutionFailureCode = "contract_invalid"
	ExecutionFailurePlatformFailed  ExecutionFailureCode = "platform_failed"
	ExecutionFailureQuotaExceeded   ExecutionFailureCode = "quota_exceeded"
	ExecutionFailureRuntimeFailed   ExecutionFailureCode = "runtime_failed"

	ExecutionFailureMessage = "execution failed"
)

func (ExecutionFailureCode) Valid added in v0.5.0 

func (c ExecutionFailureCode) Valid() bool

type ExecutionOwnerScope added in v0.5.0 

type ExecutionOwnerScope struct {
	OwnerSessionHash     string
	OwnerUserHash        string
	OwnerEnvHash         string
	SessionChannelIDHash string
}

ExecutionOwnerScope is the exact short-lived session boundary for an operation or stream. Persistent resource ownership uses sessionctx.ResourceScope.

func (ExecutionOwnerScope) Normalized added in v0.5.0 

func (s ExecutionOwnerScope) Normalized() ExecutionOwnerScope

func (ExecutionOwnerScope) Valid added in v0.5.0 

func (s ExecutionOwnerScope) Valid() bool

type Invocation 

type Invocation struct {
	Execution ExecutionContext `json:"execution"`
	Arguments map[string]any   `json:"arguments,omitempty"`
}

type OperationCanceler added in v0.3.0 

type OperationCanceler interface {
	CancelOperation(ctx context.Context, req OperationCancellation) error
}

type OperationCancellation added in v0.3.0 

type OperationCancellation struct {
	Execution   ExecutionContext `json:"execution"`
	OperationID string           `json:"operation_id"`
	Reason      string           `json:"reason,omitempty"`
	RequestedAt time.Time        `json:"requested_at"`
}

type OperationProgress added in v0.6.20 

type OperationProgress struct {
	Revision       uint64  `json:"revision"`
	Phase          string  `json:"phase"`
	CompletedUnits *uint64 `json:"completed_units,omitempty"`
	TotalUnits     *uint64 `json:"total_units,omitempty"`
	Unit           string  `json:"unit,omitempty"`
}

OperationProgress is a host-neutral progress snapshot. Phase identifiers are plugin-defined and must be localized by the plugin; the platform never persists host-authored display text.

type OperationSink added in v0.3.0 

type OperationSink interface {
	ID() string
	ReportProgress(ctx context.Context, progress OperationProgress) error
	Complete(ctx context.Context) error
	Cancel(ctx context.Context, reason string) error
	Fail(ctx context.Context, code ExecutionFailureCode, cause error) error
	CancelRequested() <-chan struct{}
}

type PermissionEvidence added in v0.3.0 

type PermissionEvidence struct {
	Required []string `json:"required"`
	Granted  []string `json:"granted"`
}

type PluginIdentity added in v0.3.0 

type PluginIdentity struct {
	PublisherID       string `json:"publisher_id"`
	PluginID          string `json:"plugin_id"`
	PluginInstanceID  string `json:"plugin_instance_id"`
	PluginVersion     string `json:"plugin_version"`
	ActiveFingerprint string `json:"active_fingerprint"`
}

type QuotaGrant added in v0.3.0 

type QuotaGrant struct {
	MaxConcurrent  int       `json:"max_concurrent,omitempty"`
	MaxDurationMS  int       `json:"max_duration_ms,omitempty"`
	MaxStreamBytes int64     `json:"max_stream_bytes,omitempty"`
	ExpiresAt      time.Time `json:"expires_at,omitempty"`
}

type Registration added in v0.3.0 

type Registration struct {
	Contract        capabilitycontract.VerifiedContract
	TargetProjector TargetProjector
	Adapter         Adapter
}

type Registry 

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

func NewRegistry 

func NewRegistry() *Registry

func (*Registry) AddContract added in v0.3.0 

func (r *Registry) AddContract(contract capabilitycontract.VerifiedContract) error

func (*Registry) Register 

func (r *Registry) Register(registration Registration) error

func (*Registry) RequireContract added in v0.3.0 

func (r *Registry) RequireContract(pin capabilitycontract.Pin) (capabilitycontract.VerifiedContract, error)

func (*Registry) Resolve added in v0.3.0 

func (r *Registry) Resolve(pin capabilitycontract.Pin) (Registration, error)

type Result 

type Result struct {
	Data any `json:"data,omitempty"`
}

type RevisionEvidence added in v0.3.0 

type RevisionEvidence struct {
	PolicyRevision     uint64 `json:"policy_revision"`
	ManagementRevision uint64 `json:"management_revision"`
	RevokeEpoch        uint64 `json:"revoke_epoch"`
}

type RiskFlag 

type RiskFlag struct {
	ID                   string       `json:"id"`
	Severity             RiskSeverity `json:"severity"`
	Summary              string       `json:"summary"`
	Description          string       `json:"description,omitempty"`
	RequiresConfirmation bool         `json:"requires_confirmation,omitempty"`
	RequiresAdmin        bool         `json:"requires_admin,omitempty"`
	DataLossRisk         bool         `json:"data_loss_risk,omitempty"`
	Destructive          bool         `json:"destructive,omitempty"`
}

type RiskPlan 

type RiskPlan struct {
	SchemaVersion        string         `json:"schema_version"`
	CapabilityID         string         `json:"capability_id,omitempty"`
	BindingID            string         `json:"binding_id,omitempty"`
	Method               string         `json:"method,omitempty"`
	TargetMethod         string         `json:"target_method,omitempty"`
	Action               string         `json:"action,omitempty"`
	Effect               Effect         `json:"effect,omitempty"`
	ResourceRef          string         `json:"resource_ref,omitempty"`
	ResourceDisplayName  string         `json:"resource_display_name,omitempty"`
	Summary              string         `json:"summary"`
	RiskFlags            []RiskFlag     `json:"risk_flags"`
	RequiresConfirmation bool           `json:"requires_confirmation,omitempty"`
	RequiresAdmin        bool           `json:"requires_admin,omitempty"`
	DataLossRisk         bool           `json:"data_loss_risk,omitempty"`
	Destructive          bool           `json:"destructive,omitempty"`
	DenyReason           string         `json:"deny_reason,omitempty"`
	Details              map[string]any `json:"details,omitempty"`
}

func NewRiskPlan 

func NewRiskPlan(inv Invocation, summary string) RiskPlan

func NormalizeRiskPlan 

func NormalizeRiskPlan(plan RiskPlan) (RiskPlan, error)

type RiskSeverity 

type RiskSeverity string
const (
	RiskSeverityInfo     RiskSeverity = "info"
	RiskSeverityLow      RiskSeverity = "low"
	RiskSeverityMedium   RiskSeverity = "medium"
	RiskSeverityHigh     RiskSeverity = "high"
	RiskSeverityCritical RiskSeverity = "critical"
)

type RouteKind added in v0.3.0 

type RouteKind string
const (
	RouteCapability RouteKind = "capability"
	RouteWorker     RouteKind = "worker"
	RouteCoreAction RouteKind = "core_action"
)

type StreamContract added in v0.3.0 

type StreamContract struct {
	EventTypeName string
	EventSchema   map[string]any
}

type StreamSink added in v0.3.0 

type StreamSink interface {
	ID() string
	Append(ctx context.Context, event any) error
	Close(ctx context.Context) error
	Fail(ctx context.Context, code ExecutionFailureCode, cause error) error
}

type SurfaceScope added in v0.3.0 

type SurfaceScope struct {
	SurfaceInstanceID    string `json:"surface_instance_id,omitempty"`
	OwnerSessionHash     string `json:"owner_session_hash,omitempty"`
	OwnerUserHash        string `json:"owner_user_hash,omitempty"`
	OwnerEnvHash         string `json:"owner_env_hash,omitempty"`
	SessionChannelIDHash string `json:"session_channel_id_hash,omitempty"`
	BridgeChannelID      string `json:"bridge_channel_id,omitempty"`
}

type TargetDescriptor added in v0.3.0 

type TargetDescriptor struct {
	Kind   string         `json:"kind"`
	Fields map[string]any `json:"fields"`
}

func CloneTargetDescriptor added in v0.5.0 

func CloneTargetDescriptor(target TargetDescriptor) (TargetDescriptor, error)

CloneTargetDescriptor validates and recursively clones target fields.

type TargetProjector added in v0.3.0 

type TargetProjector interface {
	ProjectTarget(ctx context.Context, req TargetResolutionRequest) (TargetDescriptor, error)
}

type TargetResolutionRequest added in v0.3.0 

type TargetResolutionRequest struct {
	Identity          PluginIdentity         `json:"identity"`
	Surface           SurfaceScope           `json:"surface"`
	CapabilityID      string                 `json:"capability_id"`
	CapabilityVersion string                 `json:"capability_version"`
	BindingID         string                 `json:"binding_id"`
	Contract          capabilitycontract.Pin `json:"contract"`
	Method            string                 `json:"method"`
	TargetMethod      string                 `json:"target_method"`
	TargetInput       map[string]any         `json:"target_input"`
}

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.