values

package
v0.1.0 Latest Latest
Warning

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

 Go to latest Published: Oct 3, 2026 License: MIT Imports: 30 Imported by: 0

Documentation

Overview

Package values owns the typed workflow data plane: JSON-compatible inline values, opaque artifact references, producer and classification metadata, deterministic digests, and value-set references.

Logs and compatibility set-output records are operational concerns, not Value fields. Secret references are validated and persistable, while resolved material remains an ephemeral adapter-boundary type that cannot enter Value. Shared renderers and streaming redactors fail closed for secret data; concrete secret authorities and artifact storage remain outside this package. Application-neutral artifact streaming, authorization, capture, verification, and cleanup contracts are defined here for host adapters. Expressions evaluate only from explicitly supplied typed contexts and cannot derive from secret-classified values.

Inline schemas are validated locally without resolving network or file references. The package is extraction-ready engine core. It imports only the standard library plus the adopted expression and JSON Schema dependencies and does not depend on Hadron application or persistence types.

Index

Constants

View Source 
const (
	DefaultInlineLimit int64 = 64 << 10
	MaximumInlineLimit int64 = 1 << 20
)
View Source 
const (
	// CodeExpressionSyntax identifies malformed expression-language source.
	CodeExpressionSyntax diagnostic.Code = "HADR-VALUE-001"
	// CodeExpressionUnresolved identifies a name or member absent from the
	// supplied typed evaluation context.
	CodeExpressionUnresolved diagnostic.Code = "HADR-VALUE-002"
	// CodeExpressionType identifies an expression type mismatch.
	CodeExpressionType diagnostic.Code = "HADR-VALUE-003"
	// CodeExpressionEnvDenied identifies an env reference rejected by policy.
	CodeExpressionEnvDenied diagnostic.Code = "HADR-VALUE-004"
	// CodeExpressionInvisibleStep identifies a step reference outside the
	// caller-declared visibility set.
	CodeExpressionInvisibleStep diagnostic.Code = "HADR-VALUE-005"
	// CodeInterpolation identifies malformed interpolation or a result that
	// cannot be interpolated implicitly.
	CodeInterpolation diagnostic.Code = "HADR-VALUE-006"
	// CodeExpressionValue identifies an invalid context or non-JSON result.
	CodeExpressionValue diagnostic.Code = "HADR-VALUE-007"
)
View Source 
const RedactedMarker = "[REDACTED]"

RedactedMarker is the stable replacement for secret or policy-hidden data.

Variables

View Source 
var (
	ErrArtifactInvalid      = errors.New("invalid artifact request")
	ErrArtifactAuthority    = errors.New("artifact authority unavailable")
	ErrArtifactUnauthorized = errors.New("artifact access unauthorized")
	ErrArtifactNotFound     = errors.New("artifact not found")
	ErrArtifactDigest       = errors.New("artifact digest mismatch")
	ErrArtifactExpired      = errors.New("artifact expired")
	ErrArtifactSizeLimit    = errors.New("artifact size limit exceeded")
	ErrArtifactRetention    = errors.New("artifact retention violation")
	ErrArtifactUnverified   = errors.New("artifact stream closed before digest verification")
)
View Source 
var (
	// ErrInvalidSchema identifies a declaration that cannot compile as local,
	// daemon-independent JSON Schema.
	ErrInvalidSchema = errors.New("invalid workflow value schema")
	// ErrSchemaMismatch identifies a valid schema rejected by a typed value.
	ErrSchemaMismatch = errors.New("workflow value does not satisfy schema")
)
View Source 
var (
	// ErrInvalidSecretRef marks a malformed opaque secret reference.
	ErrInvalidSecretRef = errors.New("invalid workflow secret reference")
	// ErrSecretMaterial marks secret material presented to a persistable Value
	// envelope or a value-expression operation that would unwrap it.
	ErrSecretMaterial = errors.New("workflow secret material is not persistable")
	// ErrSecretDerivation marks expression or interpolation use that would
	// unwrap, transform, or otherwise downgrade an opaque secret reference.
	ErrSecretDerivation = errors.New("workflow secret reference cannot be used in a computed expression")
)
View Source 
var (
	// ErrInvalidValue marks a malformed value, artifact, metadata, or value-set
	// reference contract.
	ErrInvalidValue = errors.New("invalid workflow value")
	// ErrAmbiguousEnvelope marks a Value JSON object that has both payloads,
	// neither payload, or a payload inconsistent with its declared type.
	ErrAmbiguousEnvelope = errors.New("ambiguous workflow value envelope")
	// ErrDigestMismatch marks inline content whose computed digest differs from
	// the digest recorded in its Value envelope.
	ErrDigestMismatch = errors.New("workflow value digest mismatch")
)
View Source 
var ErrRetentionViolation = errors.New("workflow value retention violation")

ErrRetentionViolation marks an attempt to durably store a no-retain value.

Functions

func CheckArtifactExpiry 

func CheckArtifactExpiry(operation ArtifactOperation, metadata ArtifactMetadata, at time.Time) error

CheckArtifactExpiry applies the common deterministic expiry rule.

func DigestInline 

func DigestInline(inline any) (string, error)

DigestInline returns a SHA-256 digest of the normalized JSON representation of inline. Object key order does not affect the result. Only native JSON shapes are accepted; binary slices, structs, pointers, NaN, and infinities are rejected.

func DigestValueSet 

func DigestValueSet(set ValueSet) (string, error)

DigestValueSet returns a stable SHA-256 digest over the complete named value envelopes, including classification and producer metadata.

func SHA256Digest 

func SHA256Digest(content []byte) string

SHA256Digest returns the package's stable digest representation for bytes. It does not retain, inspect, or classify the supplied content.

func ValidateDigest 

func ValidateDigest(digest string) error

ValidateDigest reports whether digest is a lower-case SHA-256 digest in the stable "sha256:<hex>" representation.

func ValidateExpressionLocalName 

func ValidateExpressionLocalName(name string) error

ValidateExpressionLocalName validates lexical aliases such as catch.bind_as. Locals use lower snake form so every accepted name is a directly addressable expression root and cannot shadow a standard workflow root.

func ValidateLiteralBindingSchema 

func ValidateLiteralBindingSchema(binding *graph.Binding, schema graph.Schema) error

ValidateLiteralBindingSchema proves that binding is the exact literal form accepted for an omitted workflow input, constructs its normalized inline value envelope, and validates that value against schema.

func ValidatePersistable 

func ValidatePersistable(value Value) error

ValidatePersistable applies data-plane invariants specific to durable state. RetentionNone values are valid ephemeral envelopes but cannot be written. SecretRef and ArtifactRef envelopes carry references only and may be stored; secret-classified inline material is rejected by Value.Validate itself.

func ValidatePersistableSet 

func ValidatePersistableSet(set ValueSet) error

ValidatePersistableSet checks named values in deterministic order.

func ValidateSchema 

func ValidateSchema(schema graph.Schema) error

ValidateSchema compiles an inline workflow value schema without requiring an instance. It is the declaration-validation path for optional values that are absent at a particular binding. Local references are supported and external resource loading is denied exactly as in ValidateValueSchema.

func ValidateValueSchema 

func ValidateValueSchema(schema graph.Schema, value Value) error

ValidateValueSchema validates one typed Value against an inline JSON Schema. Local JSON Pointer and $defs references are supported. Network, file, and other external resource loading is always rejected. The graph-native "artifact" type validates the immutable ArtifactRef projection and "secret_ref" validates an opaque canonical reference string. Plain string schemas do not accept typed secret references. An empty schema accepts every valid Value envelope.

func ValidateValueSetSchema 

func ValidateValueSetSchema(schema graph.Schema, set ValueSet) error

ValidateValueSetSchema validates the logical object formed by a named set of typed Values. Inline values contribute their JSON payload, artifacts contribute the immutable ArtifactRef projection, and secret references contribute only their canonical opaque URI. The graph-native artifact and secret_ref schema types remain identity-sensitive: an inline object or string cannot satisfy them merely because its JSON projection has the same shape. Local references and combinators retain that identity at each named value boundary. Identity-bearing entries must use exact named properties; schemas that route them through patternProperties or a schema-valued additional/unevaluatedProperties keyword are rejected explicitly, as are conditional schemas over identity-bearing entries.

Types

type ArtifactAccess 

type ArtifactAccess struct {
	Principal string    `json:"principal"`
	RunID     string    `json:"run_id,omitempty"`
	ProjectID string    `json:"project_id,omitempty"`
	At        time.Time `json:"at"`
}

ArtifactAccess contains opaque claims supplied by a host authorization boundary. At is explicit so expiry checks and tests remain deterministic.

func (ArtifactAccess) Validate 

func (a ArtifactAccess) Validate(operation ArtifactOperation) error

Validate rejects incomplete access rather than selecting an implicit principal or clock.

type ArtifactAuthorization 

type ArtifactAuthorization struct {
	Operation ArtifactOperation
	Access    ArtifactAccess
	Ref       *ArtifactRef
	Owner     *ArtifactOwner
}

ArtifactAuthorization is the complete application-neutral policy request. Ref is nil only for Put and owner-wide cleanup before an immutable reference exists. Owner is present whenever it is known without resolving storage.

type ArtifactAuthorizer 

type ArtifactAuthorizer interface {
	AuthorizeArtifact(context.Context, ArtifactAuthorization) error
}

ArtifactAuthorizer makes resolution fail closed without prescribing a host principal, ACL, or identity implementation.

type ArtifactAuthorizerFunc 

type ArtifactAuthorizerFunc func(context.Context, ArtifactAuthorization) error

ArtifactAuthorizerFunc adapts a function to ArtifactAuthorizer.

func (ArtifactAuthorizerFunc) AuthorizeArtifact 

func (f ArtifactAuthorizerFunc) AuthorizeArtifact(ctx context.Context, request ArtifactAuthorization) error

AuthorizeArtifact implements ArtifactAuthorizer.

type ArtifactCleanupKind 

type ArtifactCleanupKind string

ArtifactCleanupKind selects a deterministic cleanup boundary. 

const (
	ArtifactCleanupRun      ArtifactCleanupKind = "run"
	ArtifactCleanupProject  ArtifactCleanupKind = "project"
	ArtifactCleanupExpired  ArtifactCleanupKind = "expired"
	ArtifactCleanupPartials ArtifactCleanupKind = "partials"
	ArtifactCleanupNone     ArtifactCleanupKind = "none"
	ArtifactCleanupExternal ArtifactCleanupKind = "external"
)

func (ArtifactCleanupKind) Valid 

func (k ArtifactCleanupKind) Valid() bool

Valid reports whether k is a supported cleanup boundary.

type ArtifactCleanupOutcome 

type ArtifactCleanupOutcome string

ArtifactCleanupOutcome is an observable idempotent cleanup result. 

const (
	ArtifactCleanupDeleted           ArtifactCleanupOutcome = "deleted"
	ArtifactCleanupAlreadyAbsent     ArtifactCleanupOutcome = "already_absent"
	ArtifactCleanupNotStored         ArtifactCleanupOutcome = "not_stored"
	ArtifactCleanupPreservedExternal ArtifactCleanupOutcome = "preserved_external"
)

func (ArtifactCleanupOutcome) Valid 

func (o ArtifactCleanupOutcome) Valid() bool

Valid reports whether o is a supported cleanup result.

type ArtifactCleanupRequest 

type ArtifactCleanupRequest struct {
	Access ArtifactAccess
	Kind   ArtifactCleanupKind
	Owner  ArtifactOwner
	Ref    *ArtifactRef
	Before time.Time
}

ArtifactCleanupRequest selects owner, expiry, partial, or non-local cleanup.

func (ArtifactCleanupRequest) Validate 

func (r ArtifactCleanupRequest) Validate() error

Validate checks a cleanup request without resolving storage.

type ArtifactCleanupResult 

type ArtifactCleanupResult struct {
	Outcome      ArtifactCleanupOutcome `json:"outcome"`
	DeletedCount int                    `json:"deleted_count,omitempty"`
}

ArtifactCleanupResult exposes only an aggregate count, never references, digests, URIs, owner identifiers, local paths, or content.

func (ArtifactCleanupResult) Validate 

func (r ArtifactCleanupResult) Validate() error

Validate rejects ambiguous cleanup results. Aggregate counts deliberately avoid exposing secret artifact references or digests.

type ArtifactDeleteRequest 

type ArtifactDeleteRequest struct {
	Access ArtifactAccess
	Ref    ArtifactRef
}

ArtifactDeleteRequest requests deletion of one locally owned reference.

func (ArtifactDeleteRequest) Validate 

func (r ArtifactDeleteRequest) Validate() error

Validate checks an exact-reference deletion request without resolving it.

type ArtifactError 

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

ArtifactError is safe to render. Cause remains available through Unwrap for process-local inspection but Error and Diagnostic never format it, a URI, owner identifier, filesystem path, or payload.

func NewArtifactError 

func NewArtifactError(operation ArtifactOperation, failure ArtifactFailure, ref *ArtifactRef, cause error) *ArtifactError

NewArtifactError constructs a render-safe typed artifact failure.

func (*ArtifactError) Diagnostic 

func (e *ArtifactError) Diagnostic() diagnostic.Diagnostic

Diagnostic returns the stable structured presentation of the failure.

func (*ArtifactError) Error 

func (e *ArtifactError) Error() string

Error intentionally contains only closed vocabulary.

func (*ArtifactError) Failure 

func (e *ArtifactError) Failure() ArtifactFailure

Failure reports the stable failure category.

func (*ArtifactError) Is 

func (e *ArtifactError) Is(target error) bool

Is makes the stable failure sentinel searchable independently of the raw, process-local cause returned by Unwrap.

func (*ArtifactError) Operation 

func (e *ArtifactError) Operation() ArtifactOperation

Operation reports the failed operation.

func (*ArtifactError) Reference 

func (e *ArtifactError) Reference() *ArtifactRef

Reference returns a defensive copy for programmatic handling. Callers must apply normal redaction rules before presentation.

func (*ArtifactError) Unwrap 

func (e *ArtifactError) Unwrap() error

Unwrap exposes the raw cause to process-local error handling only.

type ArtifactFailure 

type ArtifactFailure string

ArtifactFailure classifies failures without exposing payloads or locators. 

const (
	ArtifactFailureInvalid      ArtifactFailure = "invalid"
	ArtifactFailureAuthority    ArtifactFailure = "authority"
	ArtifactFailureUnauthorized ArtifactFailure = "unauthorized"
	ArtifactFailureNotFound     ArtifactFailure = "not_found"
	ArtifactFailureDigest       ArtifactFailure = "digest"
	ArtifactFailureExpired      ArtifactFailure = "expired"
	ArtifactFailureSize         ArtifactFailure = "size"
	ArtifactFailureRetention    ArtifactFailure = "retention"
)

type ArtifactMetadata 

type ArtifactMetadata struct {
	Ref       ArtifactRef   `json:"ref"`
	Owner     ArtifactOwner `json:"owner"`
	CreatedAt time.Time     `json:"created_at"`
	ExpiresAt time.Time     `json:"expires_at,omitempty"`
}

ArtifactMetadata is the immutable storage-side record for one reference. Owner and expiry remain adapter metadata; workflow state stores only Ref.

func (ArtifactMetadata) Validate 

func (m ArtifactMetadata) Validate() error

Validate checks immutable metadata without resolving content.

type ArtifactOperation 

type ArtifactOperation string

ArtifactOperation identifies an authorization boundary. Implementations must authorize before resolving a local path or contacting a delegate. 

const (
	ArtifactOperationPut     ArtifactOperation = "put"
	ArtifactOperationOpen    ArtifactOperation = "open"
	ArtifactOperationStat    ArtifactOperation = "stat"
	ArtifactOperationDelete  ArtifactOperation = "delete"
	ArtifactOperationCleanup ArtifactOperation = "cleanup"
)

func (ArtifactOperation) Valid 

func (o ArtifactOperation) Valid() bool

Valid reports whether o is a supported artifact operation.

type ArtifactOwner 

type ArtifactOwner struct {
	Scope ArtifactOwnerScope `json:"scope"`
	ID    string             `json:"id"`
}

ArtifactOwner identifies a host-owned lifetime without importing host run or project types. ID is opaque and must never be used directly as a path.

func (ArtifactOwner) Validate 

func (o ArtifactOwner) Validate() error

Validate checks that owner is a complete local ownership claim.

type ArtifactOwnerScope 

type ArtifactOwnerScope string

ArtifactOwnerScope names the only locally durable ownership scopes. 

const (
	ArtifactOwnerRun     ArtifactOwnerScope = "run"
	ArtifactOwnerProject ArtifactOwnerScope = "project"
)

func (ArtifactOwnerScope) Valid 

func (s ArtifactOwnerScope) Valid() bool

Valid reports whether s is a supported local ownership scope.

type ArtifactPutRequest 

type ArtifactPutRequest struct {
	Store          string
	Owner          ArtifactOwner
	Metadata       Metadata
	ExpectedDigest string
	ExpectedSize   *int64
	MaxBytes       int64
	CreatedAt      time.Time
	ExpiresAt      time.Time
	Access         ArtifactAccess
}

ArtifactPutRequest describes one immutable streaming write. MaxBytes is a required hard stream limit and may be much larger than the inline cap.

func (ArtifactPutRequest) Validate 

func (r ArtifactPutRequest) Validate() error

Validate checks request invariants before an adapter consumes source.

type ArtifactReadCloser 

type ArtifactReadCloser interface {
	io.ReadCloser
	Metadata() ArtifactMetadata
	Verified() bool
}

ArtifactReadCloser is a streaming, digest-verifying artifact body.

func NewVerifyingArtifactReader 

func NewVerifyingArtifactReader(metadata ArtifactMetadata, reader io.ReadCloser) (ArtifactReadCloser, error)

NewVerifyingArtifactReader wraps a stream so successful EOF proves the immutable reference digest. Close is idempotent; closing before verified EOF deterministically returns ErrArtifactUnverified.

type ArtifactRef 

type ArtifactRef struct {
	Store     string         `json:"store"`
	URI       string         `json:"uri"`
	Digest    string         `json:"digest"`
	MediaType string         `json:"media_type"`
	SizeBytes int64          `json:"size_bytes"`
	Producer  Producer       `json:"producer"`
	Redaction RedactionClass `json:"redaction"`
	Retention RetentionClass `json:"retention"`
}

ArtifactRef describes content held outside the workflow data envelope. It carries no artifact bytes and does not prescribe a storage implementation.

func (ArtifactRef) MarshalJSON 

func (r ArtifactRef) MarshalJSON() ([]byte, error)

MarshalJSON validates an ArtifactRef before encoding it.

func (*ArtifactRef) UnmarshalJSON 

func (r *ArtifactRef) UnmarshalJSON(data []byte) error

UnmarshalJSON rejects duplicate and unknown artifact fields and validates the decoded reference without resolving it.

func (ArtifactRef) Validate 

func (r ArtifactRef) Validate() error

Validate reports incomplete or unsupported artifact metadata. It does not resolve the URI, access storage, or verify artifact bytes.

type ArtifactStore 

type ArtifactStore interface {
	Put(context.Context, ArtifactPutRequest, io.Reader) (ArtifactMetadata, error)
	Open(context.Context, ArtifactAccess, ArtifactRef) (ArtifactReadCloser, error)
	Stat(context.Context, ArtifactAccess, ArtifactRef) (ArtifactMetadata, error)
	Delete(context.Context, ArtifactDeleteRequest) (ArtifactCleanupResult, error)
	Cleanup(context.Context, ArtifactCleanupRequest) (ArtifactCleanupResult, error)
}

ArtifactStore is the extraction-ready artifact producer/resolver contract. Implementations authorize before resolution; external delegates enforce the same contract themselves.

type CaptureMode 

type CaptureMode string

CaptureMode selects the only interpretation applied before an inline value is constructed. Promoted bytes remain opaque artifact content. 

const (
	CaptureJSON         CaptureMode = "json"
	CaptureText         CaptureMode = "text"
	CaptureArtifactOnly CaptureMode = "artifact_only"
)

type CapturePolicy 

type CapturePolicy struct {
	Mode        CaptureMode
	InlineLimit int64
}

CapturePolicy bounds the only buffer used while deciding inline versus artifact storage. InlineLimit must be positive and no larger than 1 MiB.

func (CapturePolicy) Validate 

func (p CapturePolicy) Validate() error

Validate rejects configurations that could accidentally become unbounded.

type DisplayPolicy 

type DisplayPolicy struct {
	Private PrivateDisplayPolicy `json:"private,omitempty"`
}

DisplayPolicy is shared by value and event renderers.

func (DisplayPolicy) RevealsPrivate 

func (p DisplayPolicy) RevealsPrivate() bool

RevealsPrivate reports the explicit private-payload decision.

func (DisplayPolicy) Validate 

func (p DisplayPolicy) Validate() error

Validate rejects policy values other than the closed mask/reveal vocabulary.

type ExpressionContext 

type ExpressionContext struct {
	Inputs          ValueSet
	Outputs         ValueSet
	Compensation    ValueSet
	Steps           map[string]StepContext
	Item            *Value
	Index           *int
	Run             map[string]any
	RunScope        map[string]any
	ExecutionTarget map[string]any
	Env             ValueSet
	// Locals supplies explicitly declared lexical bindings such as catch.bind_as.
	// Names become top-level expression roots and must not shadow standard roots.
	Locals ValueSet `json:",omitempty"`
}

ExpressionContext contains the standard expression roots. Inputs, raw adapter Outputs used only by node-output projection, compensation evidence used only by dormant-handler input binding, step outputs, the optional fan-out item, and env enter through Value envelopes. Run, RunScope, and ExecutionTarget are host-provided JSON-compatible metadata. Env is never populated from the ambient process environment.

type ExpressionEngine 

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

ExpressionEngine evaluates workflow expressions and owns a concurrency-safe cache of immutable expr programs. The zero value is ready for use.

func NewExpressionEngine 

func NewExpressionEngine() *ExpressionEngine

NewExpressionEngine returns an expression engine with an empty program cache.

func (*ExpressionEngine) EvaluateBinding 

func (e *ExpressionEngine) EvaluateBinding(
	binding graph.Binding,
	context ExpressionContext,
	options ExpressionOptions,
	metadata Metadata,
) (Value, error)

EvaluateBinding evaluates one graph binding into a typed Value. Exact passthrough references to an input or step output preserve the complete existing envelope, including producer, redaction, retention, media type, digest, and artifact identity. Computed, literal, and interpolated results receive metadata supplied by the binding owner.

func (*ExpressionEngine) EvaluateBool 

func (e *ExpressionEngine) EvaluateBool(
	expression graph.Expression,
	context ExpressionContext,
	options ExpressionOptions,
) (bool, error)

EvaluateBool evaluates one raw graph expression as a boolean. It is the predicate path used by if and other conditional workflow constructs.

func (*ExpressionEngine) EvaluateRaw 

func (e *ExpressionEngine) EvaluateRaw(
	expression graph.Expression,
	context ExpressionContext,
	options ExpressionOptions,
) (any, error)

EvaluateRaw evaluates one raw graph expression and returns a normalized JSON-compatible native value. It rejects interpolation syntax.

func (*ExpressionEngine) Interpolate 

func (e *ExpressionEngine) Interpolate(
	template string,
	source *graph.SourceRef,
	context ExpressionContext,
	options ExpressionOptions,
) (string, error)

Interpolate evaluates every {{ expression }} segment in a string. Implicit interpolation accepts strings and JSON scalar numbers/booleans. Composite values and null require the explicit deterministic string(...) conversion.

type ExpressionError 

type ExpressionError struct {
	Diagnostic diagnostic.Diagnostic
	Cause      error
}

ExpressionError couples a stable workflow diagnostic with the underlying parser, checker, evaluator, or value-validation failure.

func (*ExpressionError) Error 

func (e *ExpressionError) Error() string

func (*ExpressionError) Unwrap 

func (e *ExpressionError) Unwrap() error

Unwrap exposes the underlying engine or value-validation error.

type ExpressionOptions 

type ExpressionOptions struct {
	AllowEnv     bool
	VisibleSteps []string
}

ExpressionOptions carries caller policy that must be enforced for every evaluation, including cache hits. AllowEnv exposes only ExpressionContext.Env. A nil VisibleSteps permits every step in the context; a non-nil slice is the complete visibility allowlist, including when it is empty.

type Metadata 

type Metadata struct {
	Producer  Producer       `json:"producer"`
	MediaType string         `json:"media_type"`
	Redaction RedactionClass `json:"redaction"`
	Retention RetentionClass `json:"retention"`
}

Metadata is the classification and provenance common to every Value.

func (Metadata) Validate 

func (m Metadata) Validate() error

Validate reports incomplete or unsupported envelope metadata.

type Observation 

type Observation struct {
	Channel    string
	Attributes map[string]string
	Payload    []byte
}

Observation is an application-neutral adapter-boundary payload. Channel is an open classifier such as command, prompt, message, http, or mcp.

type PrivateDisplayPolicy 

type PrivateDisplayPolicy string

PrivateDisplayPolicy controls whether private (never secret) payloads are visible to a renderer. Its zero value is fail-closed masking. 

const (
	PrivateDisplayMask   PrivateDisplayPolicy = "mask"
	PrivateDisplayReveal PrivateDisplayPolicy = "reveal"
)

func (PrivateDisplayPolicy) Valid 

func (p PrivateDisplayPolicy) Valid() bool

Valid reports whether p is a supported policy. Empty is the default mask.

type Producer 

type Producer struct {
	Kind      string `json:"kind"`
	Reference string `json:"reference"`
	Output    string `json:"output,omitempty"`
}

Producer identifies where a value originated without depending on a host's run, persistence, principal, or registry record types. Kind is intentionally open-ended; Reference is an opaque engine- or adapter-owned identifier, and Output optionally identifies a named output within that producer.

func (Producer) MarshalJSON 

func (p Producer) MarshalJSON() ([]byte, error)

MarshalJSON validates standalone producer metadata before encoding it.

func (*Producer) UnmarshalJSON 

func (p *Producer) UnmarshalJSON(data []byte) error

UnmarshalJSON rejects duplicate and unknown producer fields.

func (Producer) Validate 

func (p Producer) Validate() error

Validate reports missing or ambiguous producer metadata.

type RedactionClass 

type RedactionClass string

RedactionClass controls whether a value may be displayed or recorded by a consumer. Secret payloads are always masked; private display is policy-bound. 

const (
	RedactionPublic  RedactionClass = "public"
	RedactionPrivate RedactionClass = "private"
	RedactionSecret  RedactionClass = "secret"
)

func (RedactionClass) Valid 

func (c RedactionClass) Valid() bool

Valid reports whether c is a supported redaction class.

type Redactor 

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

Redactor masks a fixed set of known resolved secret byte strings. It is immutable and safe for concurrent stateless masking calls. A streaming writer created from it owns its own bounded pending buffer.

func NewRedactor 

func NewRedactor(secrets ...*ResolvedSecret) (*Redactor, error)

NewRedactor defensively copies, deduplicates, and deterministically orders resolved material. Longest matches win; equal-length matches use byte order.

func (*Redactor) MaskBytes 

func (r *Redactor) MaskBytes(input []byte) []byte

MaskBytes replaces every known occurrence without mutating input.

func (*Redactor) MaskObservation 

func (r *Redactor) MaskObservation(input Observation) Observation

MaskObservation returns a defensive copy whose attribute values and payload have been masked. Attribute keys and the channel are non-payload metadata.

func (*Redactor) MaskString 

func (r *Redactor) MaskString(input string) string

MaskString replaces every known occurrence in text.

func (*Redactor) Writer 

func (r *Redactor) Writer(destination io.Writer) io.WriteCloser

Writer returns a streaming masker. It may delay at most maxSecretLen-1 input bytes so matches spanning arbitrary Write boundaries are masked. Close flushes pending bytes but does not close the destination.

type Reference 

type Reference struct {
	Root    string
	Path    []string
	Dynamic bool
}

Reference is one structural reference to a standard expression root. Path contains statically named members. Dynamic is true when at least one member is selected by a computed expression. The contract intentionally reports references without inferring graph edges.

func ParseInterpolationReferences 

func ParseInterpolationReferences(template string, source *graph.SourceRef) ([]Reference, error)

ParseInterpolationReferences reports structural references from every raw expression segment in an interpolation template. Literal segments are not parsed and no expression is evaluated.

func ParseReferences 

func ParseReferences(expression graph.Expression) ([]Reference, error)

ParseReferences parses raw expression source and reports structural access to the standard roots. It performs no graph-edge inference and is intended to remain reusable by later compiler visibility analysis.

type RenderedValue 

type RenderedValue struct {
	Type      Type           `json:"type"`
	Payload   any            `json:"payload"`
	Producer  Producer       `json:"producer"`
	MediaType string         `json:"media_type"`
	Digest    string         `json:"digest"`
	Redaction RedactionClass `json:"redaction"`
	Retention RetentionClass `json:"retention"`
	Masked    bool           `json:"masked"`
}

RenderedValue is the stable display projection of a Value. Payload contains an inline value, ArtifactRef, or RedactedMarker and never an unmasked secret.

func RenderValue 

func RenderValue(value Value, policy DisplayPolicy) (RenderedValue, error)

RenderValue applies secret and private display policy. Secret values are always masked, including secret ArtifactRef URI metadata and SecretRef URIs.

type RenderedValueSet 

type RenderedValueSet map[string]RenderedValue

RenderedValueSet is a named display projection.

func RenderValueSet 

func RenderValueSet(set ValueSet, policy DisplayPolicy) (RenderedValueSet, error)

RenderValueSet renders every value under one shared display policy.

type ResolvedSecret 

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

ResolvedSecret holds short-lived adapter-boundary material. Its bytes are intentionally unexported, copied on ingress and access, rejected by JSON, and never represented by Value.

func NewResolvedSecret 

func NewResolvedSecret(ref SecretRef, material []byte) (*ResolvedSecret, error)

NewResolvedSecret constructs ephemeral resolved material for a reference.

func (*ResolvedSecret) Bytes 

func (s *ResolvedSecret) Bytes() []byte

Bytes returns a defensive copy for immediate adapter injection.

func (*ResolvedSecret) Forget 

func (s *ResolvedSecret) Forget()

Forget overwrites and releases the held material. It is safe to call more than once. Previously returned defensive copies remain caller-owned.

func (*ResolvedSecret) GoString 

func (*ResolvedSecret) GoString() string

GoString never reveals material or the underlying reference.

func (*ResolvedSecret) MarshalJSON 

func (*ResolvedSecret) MarshalJSON() ([]byte, error)

MarshalJSON prevents resolved material from entering persisted JSON.

func (*ResolvedSecret) Reference 

func (s *ResolvedSecret) Reference() SecretRef

Reference returns the non-secret provenance reference.

func (*ResolvedSecret) String 

func (*ResolvedSecret) String() string

String never reveals material or the underlying reference.

type RetentionClass 

type RetentionClass string

RetentionClass describes the intended lifetime and ownership of value data. Cleanup and enforcement belong to artifact-store and host adapters. 

const (
	RetentionNone     RetentionClass = "none"
	RetentionRun      RetentionClass = "run"
	RetentionProject  RetentionClass = "project"
	RetentionExternal RetentionClass = "external"
)

func (RetentionClass) Valid 

func (c RetentionClass) Valid() bool

Valid reports whether c is a supported retention class.

type SecretRef 

type SecretRef string

SecretRef is a canonical, opaque reference resolved only by a host adapter. Its URI form is secret://authority/path with an optional #field fragment. The core validates structure but assigns no meaning to authority, path, or field names.

func ParseSecretRef 

func ParseSecretRef(raw string) (SecretRef, error)

ParseSecretRef validates and returns an opaque secret reference.

func (SecretRef) Authority 

func (r SecretRef) Authority() string

Authority returns the structurally validated reference authority.

func (SecretRef) Field 

func (r SecretRef) Field() string

Field returns the optional structurally validated field fragment.

func (SecretRef) MarshalJSON 

func (r SecretRef) MarshalJSON() ([]byte, error)

MarshalJSON validates the reference before encoding its canonical string.

func (SecretRef) Path 

func (r SecretRef) Path() string

Path returns the structurally validated escaped reference path.

func (*SecretRef) UnmarshalJSON 

func (r *SecretRef) UnmarshalJSON(data []byte) error

UnmarshalJSON validates a canonical reference string.

func (SecretRef) Validate 

func (r SecretRef) Validate() error

Validate reports whether r is a canonical secret reference.

type SecretResolver 

type SecretResolver interface {
	ResolveSecret(context.Context, SecretRef) (*ResolvedSecret, error)
}

SecretResolver is the narrow host-adapter seam for resolving references. Implementations must not cache or persist returned material in workflow state. Callers should Forget the result after injection and masking setup.

type SecretResolverFunc 

type SecretResolverFunc func(context.Context, SecretRef) (*ResolvedSecret, error)

SecretResolverFunc adapts a function to SecretResolver.

func (SecretResolverFunc) ResolveSecret 

func (f SecretResolverFunc) ResolveSecret(ctx context.Context, ref SecretRef) (*ResolvedSecret, error)

ResolveSecret calls f.

type StepContext 

type StepContext struct {
	Outputs ValueSet
	Status  string
	Error   *Value
	Items   []StepContext
}

StepContext is the expression-visible state of one completed or observable node. Outputs remain typed Value envelopes until the engine unwraps a private evaluation copy. Error remains a typed Value until the engine unwraps a private evaluation copy, preserving classification for catch/finally and fan-out item errors.

type Type 

type Type string

Type identifies which payload a Value carries. 

const (
	TypeNull      Type = "null"
	TypeString    Type = "string"
	TypeNumber    Type = "number"
	TypeBoolean   Type = "boolean"
	TypeArray     Type = "array"
	TypeObject    Type = "object"
	TypeArtifact  Type = "artifact"
	TypeSecretRef Type = "secret_ref"
)

func (Type) Valid 

func (t Type) Valid() bool

Valid reports whether t is a supported value type.

type Value 

type Value struct {
	Type      Type
	Inline    any
	Artifact  *ArtifactRef
	SecretRef *SecretRef
	Producer  Producer
	MediaType string
	Digest    string
	Redaction RedactionClass
	Retention RetentionClass
}

Value is the workflow data-plane envelope. It carries exactly one JSON-compatible Inline payload, Artifact reference, or opaque SecretRef. Type makes inline null distinct from a missing payload. Resolved secret material is intentionally not a Value payload mode.

func CaptureValue 

func CaptureValue(ctx context.Context, store ArtifactStore, request ArtifactPutRequest, source io.Reader, policy CapturePolicy) (Value, error)

CaptureValue returns a small JSON/text value inline or promotes it to an immutable ArtifactRef. It buffers at most InlineLimit+1 bytes. Oversized JSON is deliberately not parsed: the original opaque bytes are streamed to the store and the result is TypeArtifact.

func NewArtifact 

func NewArtifact(ref ArtifactRef) (Value, error)

NewArtifact constructs a validated artifact Value and mirrors the reference metadata into the common Value envelope.

func NewInline 

func NewInline(inline any, metadata Metadata) (Value, error)

NewInline constructs a validated inline Value, normalizes its native JSON shape, infers its Type, and records its deterministic payload digest.

func NewSecretRef 

func NewSecretRef(ref SecretRef, metadata Metadata) (Value, error)

NewSecretRef constructs a validated reference Value. Only the opaque URI and its producer/classification metadata enter the data plane; resolved material is not accepted by this constructor.

func (Value) MarshalJSON 

func (v Value) MarshalJSON() ([]byte, error)

MarshalJSON emits the stable Value envelope and preserves inline null as an explicitly present "inline": null payload.

func (*Value) UnmarshalJSON 

func (v *Value) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes and validates a strict, unambiguous Value envelope.

func (Value) Validate 

func (v Value) Validate() error

Validate checks the closed enums, exact payload mode, JSON compatibility, metadata, and digest consistency of v.

type ValueSet 

type ValueSet map[string]Value

ValueSet is a named collection of workflow values, such as run inputs or a node invocation's outputs.

func (ValueSet) MarshalJSON 

func (s ValueSet) MarshalJSON() ([]byte, error)

MarshalJSON validates every Value before encoding a ValueSet.

func (*ValueSet) UnmarshalJSON 

func (s *ValueSet) UnmarshalJSON(data []byte) error

UnmarshalJSON rejects duplicate value names and validates the complete set.

func (ValueSet) Validate 

func (s ValueSet) Validate() error

Validate checks every named value in deterministic name order.

type ValueSetRef 

type ValueSetRef struct {
	ID     string `json:"id"`
	Digest string `json:"digest"`
}

ValueSetRef is an opaque, digest-bound reference to a persisted ValueSet. The same shape can be embedded by run, node invocation, wait, and event records without importing a host persistence identifier type.

func NewValueSetRef 

func NewValueSetRef(id string, set ValueSet) (ValueSetRef, error)

NewValueSetRef constructs a validated opaque reference bound to set's deterministic digest.

func (ValueSetRef) MarshalJSON 

func (r ValueSetRef) MarshalJSON() ([]byte, error)

MarshalJSON validates a ValueSetRef before encoding it.

func (*ValueSetRef) UnmarshalJSON 

func (r *ValueSetRef) UnmarshalJSON(data []byte) error

UnmarshalJSON rejects duplicate and unknown reference fields.

func (ValueSetRef) Validate 

func (r ValueSetRef) Validate() error

Validate reports an incomplete or malformed value-set reference.

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.