dagql

package
v1.0.0-beta.16 Latest Latest
Warning

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

 Go to latest Published: Oct 8, 2026 License: Apache-2.0 Imports: 68 Imported by: 0

Documentation

Index

Constants

View Source 
const CloudCacheID = cloudCacheID

CloudCacheID is the sending cache an engine's merges name: the Cloud.

View Source 
const InstrumentationLibrary = "dagger.io/dagql"

Variables

View Source 
var (
	DirectiveLocationQuery                = DirectiveLocations.Register("QUERY")
	DirectiveLocationMutation             = DirectiveLocations.Register("MUTATION")
	DirectiveLocationSubscription         = DirectiveLocations.Register("SUBSCRIPTION")
	DirectiveLocationField                = DirectiveLocations.Register("FIELD")
	DirectiveLocationFragmentDefinition   = DirectiveLocations.Register("FRAGMENT_DEFINITION")
	DirectiveLocationFragmentSpread       = DirectiveLocations.Register("FRAGMENT_SPREAD")
	DirectiveLocationInlineFragment       = DirectiveLocations.Register("INLINE_FRAGMENT")
	DirectiveLocationVariableDefinition   = DirectiveLocations.Register("VARIABLE_DEFINITION")
	DirectiveLocationSchema               = DirectiveLocations.Register("SCHEMA")
	DirectiveLocationScalar               = DirectiveLocations.Register("SCALAR")
	DirectiveLocationObject               = DirectiveLocations.Register("OBJECT")
	DirectiveLocationFieldDefinition      = DirectiveLocations.Register("FIELD_DEFINITION")
	DirectiveLocationArgumentDefinition   = DirectiveLocations.Register("ARGUMENT_DEFINITION")
	DirectiveLocationInterface            = DirectiveLocations.Register("INTERFACE")
	DirectiveLocationUnion                = DirectiveLocations.Register("UNION")
	DirectiveLocationEnum                 = DirectiveLocations.Register("ENUM")
	DirectiveLocationEnumValue            = DirectiveLocations.Register("ENUM_VALUE")
	DirectiveLocationInputObject          = DirectiveLocations.Register("INPUT_OBJECT")
	DirectiveLocationInputFieldDefinition = DirectiveLocations.Register("INPUT_FIELD_DEFINITION")
)
View Source 
var CacheScopeInput = ImplicitInput{
	Name: "cacheScope",
	Resolver: func(ctx context.Context, _ map[string]Input) (Input, error) {
		scope, _ := ctx.Value(perClientCacheScopeKey{}).(string)
		return NewString(scope), nil
	},
}

CacheScopeInput scopes a call ID to the named per-client cache scope on ctx (see WithPerClientCacheScope) without also mixing in the client ID. Use it on fields whose results are safe to share across clients but must still be re-resolved when a caller deliberately busts its per-client cache, such as a lock refresh that needs fresh remote metadata. Without a scope it resolves to "", so ordinary calls from every client share one result.

View Source 
var CurrentSchemaInput = ImplicitInput{
	Name: "cachePerSchema",
	Resolver: func(ctx context.Context, _ map[string]Input) (Input, error) {
		srv := CurrentDagqlServer(ctx)
		if srv == nil {
			return nil, fmt.Errorf("current dagql server not found")
		}
		return NewString(srv.SchemaDigest().String()), nil
	},
}

CurrentSchemaInput scopes a call ID to the schema digest of the dagql server currently executing the call.

View Source 
var DirectiveLocations = NewEnum[DirectiveLocation]()
View Source 
var ErrCacheClosed = errors.New("cache closed")
View Source 
var ErrCacheRecursiveCall = fmt.Errorf("recursive call detected")
View Source 
var ErrCacheSessionNotReleased = errors.New("cache session release not started")
View Source 
var ErrCacheSessionReleased = errors.New("cache session released")
View Source 
var ErrLazySessionRetryExhausted = errors.New("lazy attempt retry budget exhausted")

ErrLazySessionRetryExhausted reports exhausted foreign-session takeovers. The returned error also wraps the last producer-release cause.

View Source 
var ErrLazyTaskBusy = errors.New("lazy task already active or awaiting bookkeeping")
View Source 
var ErrPartNoProgress = errors.New("part demand is not making progress")

ErrPartNoProgress is an invariant failure, outside the reselect class: a reselect loop was refused twice at one site with the site's counters at the same values. See PartNoProgressError.

View Source 
var ErrPartReselect = errors.New("part sources changed; reselect")
View Source 
var ErrPersistStateNotReady = errors.New("persist state not ready")
View Source 
var ErrRemoteCacheBridgeClosed = errors.New("remote cache bridge closed")

ErrRemoteCacheBridgeClosed is returned by Take after the bridge detaches.

View Source 
var ErrRenewalUnavailable = errors.New("address renewal unavailable")

ErrRenewalUnavailable is the typed cause for every renewal attempt that cannot supply a fresh address: no bridge or key, a full or closed mailbox, a negative reply, the deadline, or a reply without a usable address.

View Source 
var ErrSnapshotShareIneligible = errors.New("snapshot share ineligible")

ErrSnapshotShareIneligible marks a slot the pass will not attempt. It is a skip, not a failure: it changes no row state and no lookup eligibility.

View Source 
var ErrSnapshotSharingClosed = errors.New("snapshot sharing is closed")

ErrSnapshotSharingClosed is returned by EnableSnapshotSharing after close. Reopening admission would let a fresh item outlive the drain.

View Source 
var ErrUnavailablePart = errors.New("imported filesystem part is unavailable")
View Source 
var ErrUnknownEntry = errors.New("unknown entry")

ErrUnknownEntry is returned for an entry number the cache has not registered: it never had one, or collected it.

View Source 
var ErrUnknownHolding = errors.New("unknown holding")

ErrUnknownHolding is returned for an operation on a holding the cache does not have.

View Source 
var PerCallInput = ImplicitInput{
	Name: "cachePerCall",
	Resolver: func(context.Context, map[string]Input) (Input, error) {
		return NewString(identity.NewID()), nil
	},
}

PerCallInput scopes a call ID per invocation by mixing in a random value as an implicit call input.

View Source 
var PerClientInput = ImplicitInput{
	Name: "cachePerClient",
	Resolver: func(ctx context.Context, _ map[string]Input) (Input, error) {
		clientMD, err := engine.ClientMetadataFromContext(ctx)
		if err != nil {
			return nil, fmt.Errorf("failed to get client metadata: %w", err)
		}
		if clientMD.ClientID == "" {
			return nil, fmt.Errorf("client ID not found in context")
		}
		cacheKey := clientMD.ClientID
		if scope, ok := ctx.Value(perClientCacheScopeKey{}).(string); ok && scope != "" {
			cacheKey += ":" + scope
		}
		return NewString(cacheKey), nil
	},
}

PerClientInput scopes a call ID per client by mixing in the client ID as an implicit call input.

View Source 
var PerEngineCacheInput = ImplicitInput{
	Name: "cachePerEngineCache",
	Resolver: func(ctx context.Context, _ map[string]Input) (Input, error) {
		cache, err := EngineCache(ctx)
		if err != nil {
			return nil, err
		}
		if id := cache.Identity().ID; id != "" {
			return NewString(id), nil
		}
		if cache.engineInstanceID != "" {
			return NewString(cache.engineInstanceID), nil
		}
		return nil, fmt.Errorf("engine cache has no identity")
	},
}

PerEngineCacheInput scopes a call ID to the engine's cache, so a result is reused only by the cache that computed it, including after a clean restart. Another engine's copy never matches. It is the cache's identity ID, or, for a cache without a persistence database, the engine instance's ID.

View Source 
var PerSessionInput = ImplicitInput{
	Name: "cachePerSession",
	Resolver: func(ctx context.Context, _ map[string]Input) (Input, error) {
		clientMD, err := engine.ClientMetadataFromContext(ctx)
		if err != nil {
			return nil, fmt.Errorf("failed to get client metadata: %w", err)
		}
		if clientMD.SessionID == "" {
			return nil, fmt.Errorf("session ID not found in context")
		}
		return NewString(clientMD.SessionID), nil
	},
}

PerSessionInput scopes a call ID per session by mixing in the session ID as an implicit call input.

Functions

func ArbitraryValueFunc added in v0.20.0 

func ArbitraryValueFunc(v any) func(context.Context) (any, error)

func CacheResultNumber 

func CacheResultNumber(res AnyResult) (uint64, bool)

CacheResultNumber returns the engine-local result number of a cache-backed result: the number its cache names it by, dagger.io/cache.result.id on its spans.

func ContextWithCache added in v0.21.0 

func ContextWithCache(ctx context.Context, cache *Cache) context.Context

func ContextWithCall added in v0.21.0 

func ContextWithCall(ctx context.Context, call *ResultCall) context.Context

func ContextWithOperationLeaseProvider added in v0.21.0 

func ContextWithOperationLeaseProvider(ctx context.Context, provider OperationLeaseProvider) context.Context

func ContextWithServer 

func ContextWithServer(ctx context.Context, srv *Server) context.Context

ContextWithServer returns ctx with srv as its current dagql server, as a resolver called by srv sees it.

func ContextWithTrivialField added in v0.21.0 

func ContextWithTrivialField(ctx context.Context) context.Context

func CurrentFieldIsTrivial added in v0.21.0 

func CurrentFieldIsTrivial(ctx context.Context) bool

func DecodeLosslessJSON 

func DecodeLosslessJSON(raw []byte) (any, error)

DecodeLosslessJSON decodes exactly one JSON value, keeping numbers as json.Number so integers outside the float64 mantissa survive. Trailing content after the value is an error.

func EmitOTelWait 

func EmitOTelWait(ctx context.Context, target trace.SpanContext, reason wcprof.WaitReason, startNS, endNS int64)

EmitOTelWait records, as a span link on the waiter's current span, that the waiter blocked on a target op over [startNS,endNS] — the OTel analog of native's wcprof.BeginWait. It is shared by every choke point that blocks on shared work: the cache singleflight (reason "call_exec"/"singleflight"), lazy evaluation (reason "lazy") and service start (reason "service" — emitted from core, hence exported). The waiter is the current span in ctx: the caller's own span, or — if that caller was telemetry-suppressed — the ancestor span that actually blocked, which is the correct place for the time to land. Attaching to the waiter (never fanning links onto the target) is what keeps a high-fan-in target under the link cap. One implementation so every source's wait edge is byte-identical on the wire and the loader and validator read them uniformly.

Timestamps are absolute Unix nanoseconds as decimal strings: the engine only knows wall-clock at emit time (the trace epoch is unknowable until ingest, so the loader rebases), and decimal strings round-trip exactly through Cloud's map[string]any JSON decode where a number would lose precision above 2^53.

func EndProfSpan 

func EndProfSpan(span trace.Span, errPtr *error)

EndProfSpan ends a profiling span (exec.run, service.start, call_exec, publishResult, non-resume lazy ops), charging err as its status so the loader records the op's outcome. Unlike telemetry.EndWithCause it NEVER stamps the span into the error's tracked origins: profiling spans are passthrough/support spans no frontend renders as rows, and error-origin tracking drives user-facing attribution — an error whose first origin is an unrendered span defeats the CLI's already-shown-error suppression (a redundant trailing Error: block) and renders internal spans in the origin sections (e.g. "✘ exec.run"). Origin-stamping stays with the user-visible spans (core.AroundFunc's EndWithCause); origins already tracked in the error are still linked here, exactly as EndWithCause links them, for clean OTel data. Nil-safe.

func ExpectedTypeDirective added in v0.21.1 

func ExpectedTypeDirective(typeName string) *ast.Directive

ExpectedTypeDirective creates an @expectedType(name: "Foo") directive for annotating ID arguments with their expected type.

func FormatDescription 

func FormatDescription(paras ...string) string

func HasPendingLazyComputation 

func HasPendingLazyComputation(res AnyResult) bool

HasPendingLazyComputation is a reporting query. Local stored-part opening remains operational work, but does not turn completed computation pending.

func HasPendingLazyEvaluation added in v0.21.0 

func HasPendingLazyEvaluation(res AnyResult) bool

func IDTypeNameFor added in v0.9.8 

func IDTypeNameFor(t Typed) string

func IDTypeNameForRawType added in v0.18.6 

func IDTypeNameForRawType(t string) string

func IsImportedResult 

func IsImportedResult(result AnyResult) bool

IsImportedResult reports immutable row origin, including after typed decode.

func IsInternal added in v0.10.0 

func IsInternal(ctx context.Context) bool

IsInternal returns whether the internal flag is set in the context.

func IsSkipped added in v0.18.13 

func IsSkipped(ctx context.Context) bool

func LoadIDs 

func LoadIDs[T Typed](ctx context.Context, srv *Server, ids []ID[T]) ([]T, error)

func MarkProfilingSpan 

func MarkProfilingSpan(ctx context.Context, prev trace.SpanContext) context.Context

MarkProfilingSpan records, on a context whose current span was just set to a profiling span, which span user-facing attribution should use instead: prev (the span that was current before the profiling span started) — unless prev is itself the previously marked profiling span, in which case the earlier user-facing record is kept. Exported for the profiling-span begin sites outside this package (engineutil exec.run, core service.start).

func NewDefaultHandler added in v0.15.4 

func NewDefaultHandler(es graphql.ExecutableSchema) *handler.Server

func NewWcprofLazyParentProcessor 

func NewWcprofLazyParentProcessor() sdktrace.SpanProcessor

NewWcprofLazyParentProcessor returns the span processor that stamps wcprof.parent on lazy re-pointed work spans. It must be registered on every per-client tracer provider BEFORE the LiveSpanProcessor(s) (engine/server/session.go): listed first, its OnStart sets the attribute on the shared span object before any live-start snapshot is taken, so the override reaches every per-client export — the client's own DB and every parent export processor on the same provider, so no export path can drop the stamp. The ended span always carries the attribute regardless of ordering (the loader uses the ended copy), so correctness does not depend on order — ordering only buys live consumers the attribute too.

func NoopDone added in v0.11.0 

func NoopDone(res AnyResult, cached bool, rerr *error)

func OTelProfActive 

func OTelProfActive(ctx context.Context) bool

OTelProfActive reports whether OTel profiling spans should be emitted for work under ctx: true exactly when ctx carries a live recording span (the engine's telemetry is on). Mirrors how core.AroundFunc only emits under an active tracer and keeps the telemetry-off path allocation-free.

Exported so the choke points that live outside this package can check the same condition: the executor exec-split (engine/engineutil) and service start (core). One definition keeps "is the OTel source recording here?" answered identically everywhere.

func PeekRootFields 

func PeekRootFields(r *http.Request) (bool, []string, error)

PeekRootFields returns the top-level field names selected by a GraphQL-over-HTTP request while preserving the request body for the real server. The operation to inspect is chosen by the request's operation name (or the sole operation when the document has just one).

func RecordContentPreferredDigest 

func RecordContentPreferredDigest(ctx context.Context, span trace.Span, frame *ResultCall, res AnyResult)

RecordContentPreferredDigest supplements a call span's recipe identity at completion. A returned result can provide content learned during execution or on a cache hit. Without output content, retain the request's operation shape: returning another result is not itself content evidence for this operation. Like other call telemetry, derivation failures never fail the operation.

func RegisterPersistedObjectFamily 

func RegisterPersistedObjectFamily(family PersistedObjectFamily)

RegisterPersistedObjectFamily registers a codec family at initialization. Registration is independent of schema installation: user schemas add GraphQL types, never payload families. Duplicate names or Go types panic.

func RemoveCachePersistenceStore added in v0.21.0 

func RemoveCachePersistenceStore(ctx context.Context, dbPath string) (wipedCacheID string, _ error)

RemoveCachePersistenceStore deletes the cache's persistence database. It returns the identity the database had, if it could be read, so the caller can name the cache it wiped.

func ShouldEmitTelemetry added in v0.21.0 

func ShouldEmitTelemetry(ctx context.Context, store TelemetrySeenKeyStore, callKey string, doNotCache bool) bool

func TraceEGraphDebug added in v0.21.0 

func TraceEGraphDebug(ctx context.Context, event string, args ...any)

func Tracer added in v0.11.0 

func Tracer(ctx context.Context) trace.Tracer

func TransferFixtureLazyReleaseObserver 

func TransferFixtureLazyReleaseObserver(ctx context.Context) func(string, error)

TransferFixtureLazyReleaseObserver is present only during a private operation invoked with the environment-gated fixture enabled.

func UnmarshalLosslessJSON 

func UnmarshalLosslessJSON(raw []byte, dst any) error

UnmarshalLosslessJSON decodes exactly one JSON value into dst, keeping untyped numbers as json.Number.

func UnwrapAs added in v0.16.2 

func UnwrapAs[T any](val any) (T, bool)

UnwrapAs attempts casting val to T, unwrapping as necessary.

NOTE: the order of operations is important here - it's important to first check compatibility with T before unwrapping, since sometimes T also implements Wrapper.

func UserFacingSpanContext 

func UserFacingSpanContext(ctx context.Context) trace.SpanContext

UserFacingSpanContext returns the span context user-facing attribution (error origins, container traceparent injection) should use for ctx: the current span, unless the current span is a marked profiling span, in which case the last user-facing span recorded by MarkProfilingSpan.

func ValueFunc added in v0.20.0 

func ValueFunc(v AnyResult) func(context.Context) (AnyResult, error)

func VisitPersistedCallID 

func VisitPersistedCallID(visit PersistedRefVisitor, kind PersistedRefKind, path PersistedRefPath, raw *string) (bool, error)

VisitPersistedCallID reports the row reference inside a handle-form typed call ID and writes back a replacement with the same exact type. Recipe-form IDs are typed call descriptions with no row references and pass through untouched.

func VisitPersistedRow 

func VisitPersistedRow(visit PersistedRefVisitor, kind PersistedRefKind, path PersistedRefPath, id *uint64) (bool, error)

VisitPersistedRow reports a row reference at path and writes back a replacement. It is the shared helper for codec family visitors.

func VisitPersistedSnapshotRoles 

func VisitPersistedSnapshotRoles(visit PersistedRefVisitor, kind PersistedRefKind, path PersistedRefPath, links []PersistedSnapshotRefLink) error

VisitPersistedSnapshotRoles reports every declared storage role of the owner row with one classification and writes back replaced identities in place.

func WithNamedPerClientCacheScope 

func WithNamedPerClientCacheScope(ctx context.Context, scope string) context.Context

WithNamedPerClientCacheScope is like WithPerClientCacheScope but pins the cache namespace to a caller-provided value instead of a random one. Calls made under the same scope value share a cache namespace, while a changed value invalidates it — use it to bust a client's cached reads at a controlled boundary (e.g. a bumped generation counter) rather than on every call. An empty scope leaves the client's default namespace untouched.

func WithNonInternalTelemetry added in v0.19.7 

func WithNonInternalTelemetry(ctx context.Context) context.Context

WithNonInternalTelemetry marks telemetry within the context as non-internal, so that Server.Select does not mark its spans internal.

func WithPerClientCacheScope 

func WithPerClientCacheScope(ctx context.Context) context.Context

WithPerClientCacheScope gives PerClientInput calls made with ctx a fresh cache namespace while preserving the real client metadata used by resolvers. Use it when a resolution must be re-evaluated against request-scoped state.

func WithRepeatedTelemetry added in v0.18.11 

func WithRepeatedTelemetry(ctx context.Context) context.Context

WithRepeatedTelemetry resets the state of seen cache keys so that we emit telemetry for spans that we've already seen within the session.

This is useful in scenarios where we want to see actions performed, even if they had been performed already (e.g. an LLM running tools).

Additionally, it explicitly sets the internal flag to false, to prevent Server.Select from marking its spans internal.

func WithSkip added in v0.18.13 

func WithSkip(ctx context.Context) context.Context

Types

type AllView added in v0.12.0 

type AllView struct{}

AllView is similar to the global view, however, instead of being an empty view, it's still counted as a view.

This means that each call for a field is associated with the server view, which results in slightly different caching behavior. Additionally, it can be overridden in different views.

func (AllView) Contains added in v0.12.0 

func (AllView) Contains(view call.View) bool

type AnyID added in v0.21.1 

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

AnyID is the schema type for the generic `ID!` scalar used by every object. Type-specific expectations are conveyed by @expectedType directives on fields and arguments instead of separate per-type ID scalars.

func NewAnyID added in v0.21.1 

func NewAnyID(id *call.ID) AnyID

func (AnyID) DecodeInput added in v0.21.1 

func (AnyID) DecodeInput(val any) (Input, error)

func (AnyID) Decoder added in v0.21.1 

func (a AnyID) Decoder() InputDecoder

func (AnyID) ID added in v0.21.1 

func (a AnyID) ID() (*call.ID, error)

func (AnyID) MarshalJSON added in v0.21.1 

func (a AnyID) MarshalJSON() ([]byte, error)

func (AnyID) ToLiteral added in v0.21.1 

func (a AnyID) ToLiteral() call.Literal

func (AnyID) Type added in v0.21.1 

func (AnyID) Type() *ast.Type

func (AnyID) TypeDefinition added in v0.21.1 

func (a AnyID) TypeDefinition(_ call.View) *ast.Definition

func (AnyID) TypeDescription added in v0.21.1 

func (AnyID) TypeDescription() string

func (AnyID) TypeName added in v0.21.1 

func (AnyID) TypeName() string

type AnyObjectResult added in v0.18.13 

type AnyObjectResult interface {
	AnyResult

	// ObjectType returns the type of the object.
	ObjectType() ObjectType

	// Receiver resolves the object result referenced by this result call's receiver, if any.
	Receiver(context.Context, *Server) (AnyObjectResult, error)

	// Select evaluates the field selected by the given selector and returns the result.
	//
	// The returned value is the raw Typed value returned from the field; it must
	// be instantiated with a class for further selection.
	//
	// Any Nullable values are automatically unwrapped.
	Select(context.Context, *Server, Selector) (AnyResult, error)
}

AnyObjectResult is an AnyResult that wraps a selectable value (i.e. a graph object)

type AnyResult added in v0.18.13 

type AnyResult interface {
	Typed
	Wrapper
	IDable
	RecipeIDable
	Setter

	// RecipeDigest returns the semantic recipe digest of the value.
	RecipeDigest(context.Context) (digest.Digest, error)

	// DerefValue returns an AnyResult when the wrapped value is Derefable and
	// has a value set. If the value is not derefable, it returns itself.
	DerefValue() (AnyResult, bool)

	// NthValue returns the Nth value of the wrapped value when the wrapped value
	// is an Enumerable. If the wrapped value is not Enumerable, it returns an error.
	NthValue(context.Context, int) (AnyResult, error)

	// NullableWrapped returns a nullable view over the same underlying result.
	NullableWrapped() AnyResult

	// WithContentDigest returns a new AnyResult with the given content digest.
	WithContentDigestAny(context.Context, digest.Digest, ...string) (AnyResult, error)
	// WithSessionResourceHandle returns a new AnyResult with the given session resource handle.
	WithSessionResourceHandleAny(context.Context, SessionResourceHandle) (AnyResult, error)

	HitCache() bool
	ResultCall() (*ResultCall, error)
	// contains filtered or unexported methods
}

AnyResult is a Typed value wrapped with an ID constructor. The wrapped value may be any graphql type, including scalars, objects, arrays, etc. It's a Result but as an interface and without any type params, allowing it to be passed around without knowing the concrete type at compile-time.

type ArbitraryCachedResult added in v0.20.0 

type ArbitraryCachedResult interface {
	Value() any
	HitCache() bool
}

type Argument added in v0.18.6 

type Argument struct {
	Spec InputSpec
}

func Arg added in v0.18.6 

func Arg(name string) Argument

func (Argument) Default added in v0.18.6 

func (arg Argument) Default(input Input) Argument

func (Argument) Deprecated added in v0.18.6 

func (arg Argument) Deprecated(paras ...string) Argument

func (Argument) Directive 

func (arg Argument) Directive(dir *ast.Directive) Argument

Directive attaches a GraphQL directive to the argument, e.g. ExpectedTypeDirective("Node") to convey that an ID-typed argument accepts any object (via the universal Node interface).

func (Argument) Doc added in v0.18.6 

func (arg Argument) Doc(paras ...string) Argument

func (Argument) Experimental added in v0.18.6 

func (arg Argument) Experimental(paras ...string) Argument

func (Argument) Internal added in v0.18.11 

func (arg Argument) Internal() Argument

func (Argument) LazyRef 

func (arg Argument) LazyRef() Argument

LazyRef marks an ID-typed argument as carried by reference (not evaluated) when the receiver's ID is reconstructed from its recipe. See InputSpec.LazyRef.

func (Argument) Sensitive added in v0.18.6 

func (arg Argument) Sensitive() Argument

func (Argument) View added in v0.18.6 

func (arg Argument) View(view ViewFilter) Argument

type AroundFunc 

type AroundFunc func(
	context.Context,
	*CallRequest,
) (context.Context, func(res AnyResult, cached bool, err *error))

AroundFunc is a function that is called around every non-cached selection.

It's a little funny looking. I may have goofed it. This will be cleaned up soon.

type Array 

type Array[T Typed] []T

Array is an array of GraphQL values.

func MapArrayInput 

func MapArrayInput[T Input, R Typed](opt ArrayInput[T], fn func(T) (R, error)) (Array[R], error)

func NewBoolArray 

func NewBoolArray(elems ...bool) Array[Boolean]

func NewBooleanArray added in v0.18.13 

func NewBooleanArray(elems ...bool) Array[Boolean]

func NewFloatArray 

func NewFloatArray[T constraints.Float](elems ...T) Array[Float]

func NewIntArray 

func NewIntArray[T constraints.Integer](elems ...T) Array[Int]

func NewStringArray 

func NewStringArray(elems ...string) Array[String]

func ToArray 

func ToArray[A any, T Typed](fn func(A) T, elems ...A) Array[T]

ToArray creates a new Array by applying the given function to each element of the given slice.

func (Array[T]) Element added in v0.16.3 

func (arr Array[T]) Element() Typed

func (Array[T]) Len 

func (arr Array[T]) Len() int

func (Array[T]) Nth 

func (arr Array[T]) Nth(i int) (Typed, error)

func (Array[T]) NthValue added in v0.18.13 

func (arr Array[T]) NthValue(i int, call *ResultCall) (AnyResult, error)

func (Array[T]) Type 

func (i Array[T]) Type() *ast.Type

type ArrayInput 

type ArrayInput[I Input] []I

Array is an array of GraphQL values.

func (ArrayInput[I]) DecodeInput 

func (a ArrayInput[I]) DecodeInput(val any) (Input, error)

func (ArrayInput[S]) Decoder 

func (a ArrayInput[S]) Decoder() InputDecoder

func (ArrayInput[I]) SetField 

func (d ArrayInput[I]) SetField(val reflect.Value) error

func (ArrayInput[S]) ToArray 

func (a ArrayInput[S]) ToArray() Array[S]

func (ArrayInput[S]) ToLiteral 

func (i ArrayInput[S]) ToLiteral() call.Literal

func (ArrayInput[S]) Type 

func (a ArrayInput[S]) Type() *ast.Type

type BlobAddress 

type BlobAddress struct {
	URL           string `json:"url"`
	ExpiresAtUnix int64  `json:"expiresAtUnix,omitempty"`
}

type BlobCacheUsage 

type BlobCacheUsage struct {
	// PoolValues and PoolBytes are the pool as the memory stage measures
	// it: the values in the closure of the stored roots, each counted as its
	// record's bytes plus an entry's estimate.
	PoolValues int
	PoolBytes  int64
	// PoolBlobs and PoolBlobBytes are the distinct layer blobs the pool's
	// stored parts name, as the disk stage measures them.
	PoolBlobs     int
	PoolBlobBytes int64
	// Entries, Terms, ClassSlots and Holdings are the counts the service's
	// memory estimate weighs, and RecordBytes the bytes of every stored
	// record, in the pool or not.
	Entries     int
	Terms       int
	ClassSlots  int
	Holdings    int
	RecordBytes int64
}

BlobCacheUsage is what a blob-backed cache holds, as its limits count it.

type Boolean 

type Boolean bool

Boolean is a GraphQL Boolean scalar.

func NewBoolean 

func NewBoolean(val bool) Boolean

func (Boolean) Bool 

func (b Boolean) Bool() bool

func (Boolean) DecodeInput 

func (Boolean) DecodeInput(val any) (Input, error)

func (Boolean) Decoder 

func (Boolean) Decoder() InputDecoder

func (Boolean) MarshalJSON 

func (b Boolean) MarshalJSON() ([]byte, error)

func (Boolean) SetField 

func (b Boolean) SetField(v reflect.Value) error

func (Boolean) ToLiteral 

func (b Boolean) ToLiteral() call.Literal

func (Boolean) Type 

func (Boolean) Type() *ast.Type

func (Boolean) TypeDefinition 

func (b Boolean) TypeDefinition(view call.View) *ast.Definition

func (Boolean) TypeName 

func (Boolean) TypeName() string

func (*Boolean) UnmarshalJSON 

func (b *Boolean) UnmarshalJSON(p []byte) error

type Bytes 

type Bytes []byte

Bytes is a binary-safe GraphQL scalar. It is base64-encoded at GraphQL and JSON boundaries and retained as raw bytes in DagQL inputs and call recipes.

func NewBytes 

func NewBytes(val []byte) Bytes

func (Bytes) Bytes 

func (b Bytes) Bytes() []byte

func (Bytes) DecodeInput 

func (Bytes) DecodeInput(val any) (Input, error)

func (Bytes) Decoder 

func (b Bytes) Decoder() InputDecoder

func (Bytes) MarshalJSON 

func (b Bytes) MarshalJSON() ([]byte, error)

func (Bytes) SetField 

func (b Bytes) SetField(v reflect.Value) error

func (Bytes) ToLiteral 

func (b Bytes) ToLiteral() call.Literal

func (Bytes) Type 

func (Bytes) Type() *ast.Type

func (Bytes) TypeDefinition 

func (Bytes) TypeDefinition(_ call.View) *ast.Definition

func (Bytes) TypeName 

func (Bytes) TypeName() string

func (*Bytes) UnmarshalJSON 

func (b *Bytes) UnmarshalJSON(payload []byte) error

type Cache 

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

func EngineCache added in v0.21.0 

func EngineCache(ctx context.Context) (*Cache, error)

func NewCache 

func NewCache(
	ctx context.Context,
	dbPath string,
	snapshotManager bkcache.SnapshotManager,
	snapshotGC func(context.Context) error,
	opts ...CacheOption,
) (*Cache, error)

func (*Cache) AcquireEquivalentPartSource 

func (c *Cache) AcquireEquivalentPartSource(ctx context.Context, receiver AnyResult, address PersistedPartAddress) (*PartSourceLease, error)

func (*Cache) AddExplicitDependency added in v0.21.0 

func (c *Cache) AddExplicitDependency(ctx context.Context, parent AnyResult, dep AnyResult, reason string) error

AddExplicitDependency records a retention edge from parent to dep after parent has already been published, so dep stays alive as long as parent's cache entry does. The dep may carry session-resource requirements even though the parent has settled: the recompute cascades the grown required set to the parent and every ancestor deriving its set from it, each growth bumps the affected result's requirement generation, and serve paths compare that generation against their selection-time capture, so a hit selected before the edge landed cannot be served under the old, smaller required set.

func (*Cache) AddRemoteHold 

func (c *Cache) AddRemoteHold(ctx context.Context, key HolderKey, session string) error

AddRemoteHold records that session holds the holding.

func (*Cache) ApplyHeldValueState 

func (c *Cache) ApplyHeldValueState(ctx context.Context, key HolderKey, obs HeldValueState) (RemoteChange, bool, error)

ApplyHeldValueState applies one observation of an existing holding's value state, such as an offered reply's, by its replacement count (applyHeldValueStateLocked). It never creates a holding: an observation about one that doesn't exist is dropped, and reports false.

func (*Cache) ApplyMergedReply 

func (c *Cache) ApplyMergedReply(ctx context.Context, cache CacheID, sent ValueBundle, reply MergeReply) (RemoteChange, error)

ApplyMergedReply applies an engine cache's merged reply: for each record the Cloud sent, the entry it landed on in that cache holds the value of the record's Cloud entry, named by the record's SenderNumber. Merge on an engine runs in no session and no span names what it made, so the reply creates a holding that doesn't exist yet. Each target's value state is the reply's, at the target's replacement count: its actual dependencies, its complete and offered parts, and its own expiry. The roots' retention is one more observation, at the reply's generation and engine time. A record whose Cloud entry is gone is skipped.

It collects nothing. It returns the holdings it created or released an owner of, for the next CollectRemoteHoldings, and the recipes it affected.

func (*Cache) AttachRemoteCacheBridge 

func (c *Cache) AttachRemoteCacheBridge() (bridge *RemoteCacheBridge, created bool, err error)

AttachRemoteCacheBridge publishes this cache's renewal mailbox. A live attachment is returned again with created=false and no added ownership; otherwise a new mailbox with a fresh epoch is published. A closing cache refuses.

func (*Cache) AttachRemoteHolding 

func (c *Cache) AttachRemoteHolding(ctx context.Context, key HolderKey, desc RemoteHolding) (RemoteChange, error)

AttachRemoteHolding records an engine cache's entry as its call span reports it. The holding is found by key, or attached to the entry of its stored recipe, which is created when the cache has none; holdings that named the new holding's number as a dependency then own it. The entry learns the call's identity: the recipe, the request digest as an equivalence, the term and the content digest. The holding merges the expiry and adds the dependencies and complete parts. A holding it creates is a candidate for collection: it has no owner until a hold, retention or a dependent names it.

func (*Cache) AttachResult added in v0.21.0 

func (c *Cache) AttachResult(ctx context.Context, sessionID string, resolver TypeResolver, res AnyResult) (AnyResult, error)

func (*Cache) AvailablePart 

func (c *Cache) AvailablePart(number uint64, address PersistedPartAddress) (PartAvailability, error)

AvailablePart reports what the cache has of a part of the entry numbered number, read under one hold with the clock:

  • stored: the entry, while its value has not expired, or else an unexpired entry of its class, has the part in its blob store: a stored part is available only while the value it belongs to is;
  • absent: the stored record of the entry, expired or not, or of an unexpired entry of its class, maps the part as absent through the transfer codec, read from the stored envelope, never a decoded value. Absence is a property of the value's structure, not of its freshness;
  • otherwise unavailable.

Among the class's other entries, the lowest number answers first. Part is a copy of the stored part. Only a blob-backed cache answers.

func (*Cache) BeginOriginal 

func (c *Cache) BeginOriginal(ctx context.Context, check *SourceCheck) (*OriginalPermit, GateOutcome, error)

func (*Cache) BindSessionResource added in v0.21.0 

func (c *Cache) BindSessionResource(_ context.Context, sessionID string, clientID string, handle SessionResourceHandle, value any) error

func (*Cache) BlobCacheUsage 

func (c *Cache) BlobCacheUsage() (BlobCacheUsage, error)

BlobCacheUsage measures the cache, read under one hold. Only a blob-backed cache answers.

func (*Cache) BootRestoredResults 

func (c *Cache) BootRestoredResults() int

BootRestoredResults returns the number of entries the cache's boot restore installed, not counting type definitions: entries whose call is profile-skipped.

func (*Cache) CapturePersistedRecord 

func (c *Cache) CapturePersistedRecord(ctx context.Context, result AnyResult) (PersistedRecord, error)

CapturePersistedRecord copies one registered row without evaluating it or opening its snapshots. The returned record owns its bytes and still uses local result IDs. It is the encoding step of live metadata export, not a portable graph: callers must separately capture and relocate its references. A row being evaluated reports ErrPersistStateNotReady; unstarted work is encoded with its original inputs.

func (*Cache) CheckPartSources 

func (c *Cache) CheckPartSources(ctx context.Context, res AnyResult, address PersistedPartAddress, drain *DrainTicket, demand *PartDemandState) (PartSourceScan, error)

func (*Cache) Checkpoint 

func (c *Cache) Checkpoint(ctx context.Context) error

Checkpoint saves a blob-backed cache, the Cloud's, without closing it: the same save as Close's, the closure of the stored roots in one transaction, with each value's stored parts. A crash during a save keeps the previous one, and a blob-backed cache restores the last save whatever ended the process (NewCache). Only a blob-backed cache checkpoints while it runs: it never decodes a value, so its save copies stored records as they are.

func (*Cache) Close added in v0.21.0 

func (c *Cache) Close(ctx context.Context) error

func (*Cache) CloseDiscardingPersistence added in v0.21.0 

func (c *Cache) CloseDiscardingPersistence() error

func (*Cache) CloseWithShutdownError 

func (c *Cache) CloseWithShutdownError(ctx context.Context, cause error) error

CloseWithShutdownError is Close for a shutdown that has already failed. A non-nil cause keeps the persistence checkpoint dirty even if drain and cleanup succeed, and is returned joined with any close errors. It shares Close's once, as does CloseDiscardingPersistence: after either has run, it returns that earlier result and makes no checkpoint attempt.

func (*Cache) CollectRemoteHolding 

func (c *Cache) CollectRemoteHolding(ctx context.Context, key HolderKey) ([]HolderKey, bool, error)

CollectRemoteHolding removes one holding outright, for a gone answer: its cache no longer has the entry, and a number names one entry for the life of its cache identity, so the answer is final. Its sessions' holds and its retention go with it, and its dependents' edges to it become unknown numbers, as for any dependency whose holding is gone. Its unit on its entry is released, and dagql's collection removes the entry if nothing else owns it. It returns as candidates the holdings it depended on, for the next CollectRemoteHoldings, which cascades; it reports false when the cache has no such holding. Entries it removes count toward the next check of the classes' compaction, which only CollectRemoteHoldings runs (compactEqClassesAfterCollectionLocked).

func (*Cache) CollectRemoteHoldings 

func (c *Cache) CollectRemoteHoldings(ctx context.Context, candidates []HolderKey) ([]HolderKey, error)

CollectRemoteHoldings collects every candidate left with no session hold, no retention and no dependent, then the holdings only they owned, through holding dependencies. Each collected holding releases its entry's ownership unit, so entries left with no holding and no other owner are collected too. It returns the collected holdings' keys, sorted.

It then compacts the e-graph's classes, at most once per eqClassCheckInterval and only when something changed since the last check (compactEqClassesAfterCollectionLocked), which renumbers them. Only the Cloud calls it, and never with snapshot sharing enabled, whose pending queue keeps class IDs. Engines compact through prune.

func (*Cache) CommitReadyPart 

func (c *Cache) CommitReadyPart(ctx context.Context, p *PreparedReadyPart) (_ *ReadyPartReceipt, outcome PartInstallOutcome, rerr error)

func (*Cache) CompactEqClasses 

func (c *Cache) CompactEqClasses(ctx context.Context) (oldSlots, newSlots int, rerr error)

CompactEqClasses frees, now, every class slot that no term and no entry uses: the forced form of the check CollectRemoteHoldings makes (compactEqClassesAfterCollectionLocked). It runs whatever the time since the last check, however few classes are dead, and frees every slot when no class is live. It returns the class slots before and after. It counts as that check, so the next collection checks again only after eqClassCheckInterval.

Only a blob-backed cache answers, and never with snapshot sharing enabled, whose pending queue keeps class IDs: then, or when ctx is done before the compaction starts, it returns an error and changes nothing. A compaction that has started is not interrupted.

func (*Cache) DebugEGraphSnapshot added in v0.21.0 

func (c *Cache) DebugEGraphSnapshot() *EGraphDebugSnapshot

func (*Cache) DetachRemoteCacheBridge 

func (c *Cache) DetachRemoteCacheBridge(bridge *RemoteCacheBridge) (detached bool)

DetachRemoteCacheBridge retires exactly this attachment, completing its exchanges as unavailable. Nil, stale and repeated detach return false and leave a newer attachment alone.

func (*Cache) DropStoredParts 

func (c *Cache) DropStoredParts(blob digest.Digest) ([]StoredPart, error)

DropStoredParts removes every stored part whose layer chain names the blob, on every entry, and returns them, sorted. The service calls it when the blob store no longer has the blob, so that no later bundle or offer carries those parts. It changes nothing else: the values, and the entries their parts named, stay.

func (*Cache) EnableSnapshotSharing 

func (c *Cache) EnableSnapshotSharing() error

EnableSnapshotSharing admits early sharing on a live cache. The engine calls it after restored ownership is ready and old transfer pins are released, and only on an engine that can receive imports. It is idempotent and is refused once close has run.

func (*Cache) EnableTransferFixtureParts 

func (c *Cache) EnableTransferFixtureParts()

func (*Cache) EndRemoteProcess 

func (c *Cache) EndRemoteProcess(ctx context.Context, cache CacheID, sessions []string) []HolderKey

EndRemoteProcess ends the sessions of one process of an engine cache, releasing their holds. What its retention and dependencies own stays, under the same keys, for the cache's next process. The holdings the sessions held are candidates for collection.

func (*Cache) EntryInfo 

func (c *Cache) EntryInfo(number uint64) (RemoteEntryInfo, bool)

EntryInfo returns the same as RemoteEntryInfo for the entry numbered number, read under one hold. It reports false when the cache has no such entry.

func (*Cache) EntryStats added in v0.20.0 

func (c *Cache) EntryStats() CacheEntryStats

func (*Cache) EquivalentEntries 

func (c *Cache) EquivalentEntries(dig string) []uint64

EquivalentEntries returns the numbers of the entries in the class that dig names, sorted, read under one hold. It is nil when no class has the digest. An entry's number stays its own across the classes' renumbering, so the numbers are safe to keep past the call.

func (*Cache) EquivalentHolders 

func (c *Cache) EquivalentHolders(dig string) []HolderKey

EquivalentHolders returns the holdings on the entries of the class of digest, sorted.

func (*Cache) Evaluate added in v0.21.0 

func (c *Cache) Evaluate(ctx context.Context, results ...AnyResult) error

func (*Cache) EvaluateParts 

func (c *Cache) EvaluateParts(ctx context.Context, res AnyResult, parts ...PartKey) (rerr error)

EvaluateParts forces only the named parts of one result. On a value that does not implement HasLazyEvaluationParts every part is filled by the whole-result group, so this degenerates to Evaluate; the same conservative fallback applies when no parts are named.

func (*Cache) EvaluateTransferFixtureRoots 

func (c *Cache) EvaluateTransferFixtureRoots(ctx context.Context, sessionID string, resolver TypeResolver, ids []*call.ID) error

EvaluateTransferFixtureRoots demands the exact held fixture rows. An ordinary handle load can select a completed equivalent instead, which does not exercise acquisition or restored ownership on the row the fixture is inspecting.

func (*Cache) FinishReadyPart 

func (c *Cache) FinishReadyPart(ctx context.Context, receipt *ReadyPartReceipt) (rerr error)

func (*Cache) GetOrInitArbitrary added in v0.20.0 

func (c *Cache) GetOrInitArbitrary(
	ctx context.Context,
	sessionID string,
	callKey string,
	fn func(context.Context) (any, error),
) (ArbitraryCachedResult, error)

func (*Cache) GetOrInitCall added in v0.20.0 

func (c *Cache) GetOrInitCall(
	ctx context.Context,
	sessionID string,
	resolver TypeResolver,
	req *CallRequest,
	fn func(context.Context) (AnyResult, error),
) (AnyResult, error)

Core cache lookup/insert flow is intentionally centralized here.

func (*Cache) HoldEntry 

func (c *Cache) HoldEntry(ctx context.Context, number uint64) (AnyResult, func(context.Context) error, error)

HoldEntry holds the registered entry numbered number, without a session, and returns it undecoded, as a result an export and OfferParts accept, with a function that releases the hold.

The hold is an ownership unit on the entry, like a task's. While it lasts the entry is not collected, and it counts as a use: a publication or merge that finds the entry's value expired retires the entry rather than replacing its value in place, so what an export or offer reads of the entry stays that one value.

It refuses an entry known only through other caches' holdings, which has no value (errEntryHasNoValue). A cached nil result has one, and is held.

func (*Cache) HolderClosure 

func (c *Cache) HolderClosure(key HolderKey) []HolderKey

HolderClosure returns the holding and every holding it depends on, transitively, through its cache's own dependencies: what that engine cache exports for it. It is empty when the cache has no such holding.

func (*Cache) Identity 

func (c *Cache) Identity() CacheIdentity

Identity returns the cache's identity, zero for a cache without a persistence database.

func (*Cache) InstallReadyPart 

func (c *Cache) InstallReadyPart(ctx context.Context, receiver AnyResult, source *PartSourceLease, permit *PartPermit) error

func (*Cache) LiveBlobs 

func (c *Cache) LiveBlobs() ([]digest.Digest, error)

LiveBlobs returns every layer blob a stored part names, in the pool or not, sorted: the blobs a sweep of the blob store keeps. Only a blob-backed cache answers.

func (*Cache) LoadPersistedObjectByResultID added in v0.21.0 

func (c *Cache) LoadPersistedObjectByResultID(ctx context.Context, dag *Server, resultID uint64) (AnyObjectResult, error)

func (*Cache) LoadResultByResultID added in v0.21.0 

func (c *Cache) LoadResultByResultID(ctx context.Context, sessionID string, dag *Server, resultID uint64) (AnyResult, error)

func (*Cache) LoadResultByResultIDForSchema 

func (c *Cache) LoadResultByResultIDForSchema(ctx context.Context, sessionID string, dag *Server, recordedID uint64, installed []SchemaModuleCandidate) (AnyResult, error)

func (*Cache) MakeResultUnpruneable added in v0.21.0 

func (c *Cache) MakeResultUnpruneable(ctx context.Context, res AnyResult) error

func (*Cache) MergeValues 

func (c *Cache) MergeValues(ctx context.Context, from CacheID, input ValueBundle) (MergeReply, error)

MergeValues merges a bundle of transferred values into the cache, and replaces a fresh import: every record lands on its recipe's current entry when the cache has one. The Cloud calls it to store an engine's export, from that engine's cache; an engine calls it for the Cloud's merge, from cloudCacheID.

It derives each record's recipe outside the graph lock, in a private cache with provisional numbers, as an import did. An engine prepares a record its cache already holds a value for from its call and offers only, since merge keeps that value. Then, in one hold of egraphMu, it picks every record's target and decides it, relocates the records to the final numbers and runs every check that can fail, and only then changes the cache. The decision starts again in two cases: an entry whose dependency attachment is still open is waited on first, and a decision that installs a record prepared from its call and offers only prepares the bundle in full first.

For each record, by its recipe's current entry:

  • none: a new entry stores the record;
  • an entry with no value, known only through holdings: it stores the record, and its replacement count stays;
  • an unexpired value: the entry keeps it, since the same recipe means an interchangeable value;
  • an expired value and an unexpired record: the Cloud replaces the value in place. An engine does the same when nothing uses the entry, and otherwise retires it and stores the record in a new entry;
  • both expired: the entry keeps its value and adds only what it lacks.

Every target learns the record's identity, and the sender's holding: on an engine its Cloud holding, on the Cloud the sending engine's holding at the record's replacement count. Unexpired roots are retained. An engine admits the bundle's parts as offers by what the target kept; the Cloud admits none until it has the bytes (SetStoredPart). An expired root is answered expired, and only what the live roots need is merged.

The reply reports every target as the commit left it, read under the same lock, with the cache's generation and clock. Merge runs in no session and emits no span.

func (*Cache) MetadataEstimate added in v0.21.9 

func (c *Cache) MetadataEstimate() CacheMetadataEstimate

MetadataEstimate returns the current structural estimate of DAGQL cache memory. It reads maintained counts and does not inspect payloads or measure physical cache usage.

func (*Cache) ObserveRemoteRetention 

func (c *Cache) ObserveRemoteRetention(ctx context.Context, key HolderKey, obs RetentionObservation) ([]HolderKey, error)

ObserveRemoteRetention applies one observation of the holding's retention edge: the latest observation, by generation and then engine time, sets it. A holding left without retention is a candidate for collection.

func (*Cache) OfferParts 

func (c *Cache) OfferParts(ctx context.Context, receiver AnyResult, offers []CloudPartOffer) (out []OfferDisposition, rerr error)

OfferParts is an engine control operation. It publishes descriptions without evaluating outputs or checking the control caller's session resources.

func (*Cache) OpenedExisting 

func (c *Cache) OpenedExisting() bool

OpenedExisting reports that the cache opened an existing database rather than creating one or wiping the one it found.

func (*Cache) PartContentSource 

func (c *Cache) PartContentSource() *PartContentSource

PartContentSource returns the source constructed with the cache.

func (*Cache) PersistedResultID added in v0.21.0 

func (c *Cache) PersistedResultID(res AnyResult) (uint64, error)

func (*Cache) PersistedResults 

func (c *Cache) PersistedResults() int

PersistedResults returns the number of entries the cache's last successful persistence, normally at Close, wrote.

func (*Cache) PersistedSnapshotLinksByResultID added in v0.21.0 

func (c *Cache) PersistedSnapshotLinksByResultID(ctx context.Context, resultID uint64) ([]PersistedSnapshotRefLink, error)

func (*Cache) PersistenceResetReason added in v0.21.0 

func (c *Cache) PersistenceResetReason() CachePersistenceResetReason

func (*Cache) PlaceOffer 

func (c *Cache) PlaceOffer(receiver HolderKey, part PersistedPartOffer) (PersistedPartOffer, bool, error)

PlaceOffer places a part stored on the Cloud for an offer to the engine cache of receiver. Each service entry is mapped to that cache's entry for it: one of the cache's unexpired holdings on an entry of the service entry's class, which includes its recipe's, the lowest number first. An expired holding is an entry the engine no longer serves. The mapping reads the classes under one hold. It reports false when a service can't be mapped: the part is not placed.

func (*Cache) PrepareOriginal 

func (c *Cache) PrepareOriginal(ctx context.Context, receiver AnyResult, group LazyGroupAddress, writeSet []PersistedPartAddress, task *PartTaskToken) (*DrainTicket, GateOutcome, error)

func (*Cache) PrepareReadyPart 

func (c *Cache) PrepareReadyPart(ctx context.Context, receiver AnyResult, source *PartSourceLease, permit *PartPermit) (*PreparedReadyPart, error)

PrepareReadyPart is the public single-demand preparation: the nil-base wrapper over prepareReadyPartFromBase, which records an empty predecessor list and the ordinary observed-representation guard.

func (*Cache) Prune added in v0.21.0 

func (c *Cache) Prune(ctx context.Context, policies []CachePrunePolicy) (CachePruneReport, error)

func (*Cache) PruneMetadataEstimate added in v0.21.9 

func (c *Cache) PruneMetadataEstimate(ctx context.Context, maximumBytes, targetBytes int64) (report CacheMetadataPruneReport, rerr error)

PruneMetadataEstimate removes cold persisted roots when the coarse DAGQL structural estimate exceeds maximumBytes. It deliberately skips physical usage measurement and returns only aggregate information.

func (*Cache) RecipeDigestForCall added in v0.21.0 

func (c *Cache) RecipeDigestForCall(frame *ResultCall) (digest.Digest, error)

func (*Cache) RecipeIDForCall added in v0.21.0 

func (c *Cache) RecipeIDForCall(ctx context.Context, frame *ResultCall) (*call.ID, error)

func (*Cache) ReleaseRemoteCache 

func (c *Cache) ReleaseRemoteCache(ctx context.Context, cache CacheID) []HolderKey

ReleaseRemoteCache releases the holds and retention of every holding of an engine cache, and returns them all as candidates: collection removes them, through their dependencies on each other.

func (*Cache) ReleaseRemoteSession 

func (c *Cache) ReleaseRemoteSession(ctx context.Context, cache CacheID, session string) []HolderKey

ReleaseRemoteSession releases every hold of one session of an engine cache. The holdings it held are candidates for collection.

func (*Cache) ReleaseSession added in v0.21.0 

func (c *Cache) ReleaseSession(ctx context.Context, sessionID string) error

ReleaseSession marks a session dead immediately. Its return means cleanup is complete or irrevocably assigned to the last active cache operation; cleanup hooks may therefore run later on that operation's goroutine. Every cleanup error is accumulated for Cache.Close; deferred errors are also logged on the goroutine that observes them because ReleaseSession has already returned.

func (*Cache) RemoteEntryInfo 

func (c *Cache) RemoteEntryInfo(key HolderKey) (RemoteEntryInfo, bool)

RemoteEntryInfo returns what the cache holds for the entry of one holding, read under one hold.

func (*Cache) ResolveSessionResource added in v0.21.0 

func (c *Cache) ResolveSessionResource(
	ctx context.Context,
	sessionID string,
	clientID string,
	handle SessionResourceHandle,
) (any, error)

func (*Cache) ResolveSessionResourceCandidates added in v0.21.0 

func (c *Cache) ResolveSessionResourceCandidates(
	_ context.Context,
	sessionID string,
	clientID string,
	handle SessionResourceHandle,
) ([]SessionResourceCandidate, error)

func (*Cache) ResolveVolatileVars added in v0.21.4 

func (c *Cache) ResolveVolatileVars(_ context.Context, sessionID string) map[string]string

func (*Cache) ResultCallByResultID added in v0.21.0 

func (c *Cache) ResultCallByResultID(ctx context.Context, sessionID string, resultID uint64) (*ResultCall, error)

func (*Cache) ResultInstallSpans added in v0.21.0 

func (c *Cache) ResultInstallSpans(sessionID string, res AnyResult) []trace.SpanContext

ResultInstallSpans returns install span contexts recorded for res in the given session — i.e. the API spans whose call returned (or owns) this result. Used to attribute later runtime failures (e.g. a service exiting early) back to the API span that installed the value.

func (*Cache) RunLazyTask 

func (c *Cache) RunLazyTask(ctx context.Context, receiver AnyResult, key LazyGroupKey, spec LazyTaskSpec) (rerr error)

func (*Cache) SetPartContentSource 

func (c *Cache) SetPartContentSource(override PartContentOverride)

SetPartContentSource installs or clears the source's override. The cache must come from NewCache.

func (*Cache) SetPartPreparationContext 

func (c *Cache) SetPartPreparationContext(prepare PartPreparationContext) error

SetPartPreparationContext registers the engine's preparation callback. It is set once, before live sharing admission: a replacement, a first registration after admission was enabled and any registration after close are initialization errors. NewCache defaults it to nil.

func (*Cache) SetStoredPart 

func (c *Cache) SetStoredPart(ctx context.Context, number uint64, part PersistedPartOffer, copyExpiresAtUnix int64) (bool, error)

SetStoredPart records that part's layer chain is in the cache's blob store, for the entry with the number. The part was uploaded from a copy of the entry's recipe that expires at copyExpiresAtUnix (0: never). It is admitted against the value the entry holds now, by the rule for attaching parts to values: a copy that has not expired is interchangeable with it, and an expired copy's part attaches only while the entry's value has expired too, as the same expired value. Storing a part adds the entries its owner and services name as the entry's dependencies, as installing a part does on an engine, so they live as long as the value; a part that names an entry the cache doesn't have, an entry with no value, or one that reaches the entry, is not stored. A named entry can have lost its value to a prune between the export's merge, which kept it through its sender's holding only, and this call: storing the part would leave a value whose bundle can never be built. It reports whether the part was stored. A metadata part carries no bytes and is never stored.

func (*Cache) SetVolatileVars added in v0.21.4 

func (c *Cache) SetVolatileVars(_ context.Context, sessionID, k, v string) error

func (*Cache) Size added in v0.20.0 

func (c *Cache) Size() int

func (*Cache) SnapshotSharingEnabled 

func (c *Cache) SnapshotSharingEnabled() bool

SnapshotSharingEnabled reports whether admission is on.

func (*Cache) StoredBundle 

func (c *Cache) StoredBundle(ctx context.Context, roots []uint64) (StoredBundleResult, error)

StoredBundle builds a bundle from the entries of a blob-backed cache, the Cloud's, for a merge into an engine (design 7.5). In one hold of egraphMu it walks the closure of the roots, over their dependencies and the entries that the owners and services of their own stored parts name, and copies every record: a replacement of a stored record, which takes the lock for writing, never mixes into it. Records are relocated to ordinals, with the entry's number as SenderNumber and its replacement count.

Outputs follow section 5.1 point 3:

  • an entry's own stored parts travel with its record, expired or not, as they belong to that value, with their owners and services;
  • a part the entry's record declares and it doesn't store is borrowed from an unexpired entry of its class, the lowest number first, through the placement rule, with its services mapped to rows of this closure of the same class. A part whose services can't be mapped is left out.

func (*Cache) StoredState 

func (c *Cache) StoredState() (StoredState, error)

StoredState returns what the cache stores, read under one hold. Only a blob-backed cache answers.

func (*Cache) SyncResultSnapshotOwnerLeases added in v0.21.0 

func (c *Cache) SyncResultSnapshotOwnerLeases(ctx context.Context, res AnyResult) (rerr error)

func (*Cache) TeachCallEquivalentToResult added in v0.21.0 

func (c *Cache) TeachCallEquivalentToResult(ctx context.Context, sessionID string, frame *ResultCall, res AnyResult) error

func (*Cache) TeachContentDigest added in v0.21.0 

func (c *Cache) TeachContentDigest(ctx context.Context, res AnyResult, contentDigest digest.Digest, additionalLabels ...string) error

func (*Cache) TransferFixtureSnapshot 

func (c *Cache) TransferFixtureSnapshot(ctx context.Context, sessionID string, ids []*call.ID) (report TransferFixtureReport, rerr error)

TransferFixtureSnapshot copies raw metadata without demanding values or retaining rows. Filesystem counters are read separately by the fixture.

func (*Cache) TryAcquire 

func (c *Cache) TryAcquire(ctx context.Context, receiver AnyResult, address PersistedPartAddress, task *PartTaskToken) (*PartPermit, GateOutcome, error)

func (*Cache) TryAcquireForDecision 

func (c *Cache) TryAcquireForDecision(ctx context.Context, receiver AnyResult, address PersistedPartAddress, drain *DrainTicket, task *PartTaskToken) (*PartPermit, GateOutcome, error)

func (*Cache) UpdateRemoteHolding 

func (c *Cache) UpdateRemoteHolding(ctx context.Context, key HolderKey, update RemoteHoldingUpdate) (RemoteChange, bool, error)

UpdateRemoteHolding applies what a later report of an existing holding carries, completed parts, a learned content digest and dependencies, as one observation of its value state at the report's replacement count. It reports false, and changes nothing, when the cache has no such holding: a lazy span or share event never creates one. A higher count can drop dependencies, whose holdings it returns as candidates.

func (*Cache) UsageEntriesAll added in v0.21.0 

func (c *Cache) UsageEntriesAll(ctx context.Context) []CacheUsageEntry

func (*Cache) WaitSessionRelease 

func (c *Cache) WaitSessionRelease(ctx context.Context, sessionID string) error

WaitSessionRelease waits for cleanup started by ReleaseSession to finish. Unlike ReleaseSession, its return is a completion barrier: all per-session cleanup hooks have returned and no cache operation can produce more work for the session. Callers must first call ReleaseSession to tombstone the session.

func (*Cache) WalkResultCall added in v0.21.0 

func (c *Cache) WalkResultCall(rootCall *ResultCall, visit func(*ResultCallRef, *ResultCall) error) error

func (*Cache) WipedCacheID 

func (c *Cache) WipedCacheID() string

WipedCacheID returns the identity of the persistence database the cache wiped when it opened, if it wiped one that had an identity.

func (*Cache) WithExportedValues 

func (c *Cache) WithExportedValues(ctx context.Context, selection ValueSelection, cfg config.RefConfig, consume func(context.Context, *ExportedValues) error) (rerr error)

WithExportedValues captures the selected closure and lends it to consume. It is a capture and never waits: if any row of the closure has a task in flight (an evaluation, a part installation, a sharing slot) it returns ErrPersistStateNotReady having kept nothing, and the caller retries later.

func (*Cache) WithTransferFixtureRoots 

func (c *Cache) WithTransferFixtureRoots(ctx context.Context, sessionID string, ids []*call.ID, consume func([]AnyResult) error) (rerr error)

WithTransferFixtureRoots lends exact registered rows to the gated test fixture. It neither decodes values nor creates lasting session ownership.

func (*Cache) WriteDebugCacheSnapshot added in v0.21.0 

func (c *Cache) WriteDebugCacheSnapshot(w io.Writer) error

type CacheDebugArbitraryCall added in v0.21.0 

type CacheDebugArbitraryCall struct {
	CallKey           string `json:"call_key"`
	Waiters           int    `json:"waiters"`
	OwnerSessionCount int    `json:"owner_session_count"`
	Completed         bool   `json:"completed"`
	HasValue          bool   `json:"has_value"`
	ValueType         string `json:"value_type,omitempty"`
	Error             string `json:"error,omitempty"`
}

type CacheDebugOfferOwner 

type CacheDebugOfferOwner struct {
	OwnerID        uint64               `json:"owner_id"`
	OriginResultID uint64               `json:"origin_result_id,omitempty"`
	Address        PersistedPartAddress `json:"address"`
	HoldCount      int64                `json:"hold_count"`
	SlotCount      int64                `json:"slot_count"`
	DependencyIDs  []uint64             `json:"dependency_ids,omitempty"`
}

type CacheDebugOngoingCall added in v0.21.0 

type CacheDebugOngoingCall struct {
	CallKey           string `json:"call_key"`
	ConcurrencyKey    string `json:"concurrency_key,omitempty"`
	Waiters           int    `json:"waiters"`
	IsPersistable     bool   `json:"is_persistable"`
	TTLSeconds        int64  `json:"ttl_seconds,omitempty"`
	Completed         bool   `json:"completed"`
	Error             string `json:"error,omitempty"`
	SharedResultID    uint64 `json:"shared_result_id,omitempty"`
	ResultDescription string `json:"result_description,omitempty"`
	ResultRecordType  string `json:"result_record_type,omitempty"`
	ResultTypeName    string `json:"result_type_name,omitempty"`
}

type CacheDebugResult added in v0.21.0 

type CacheDebugResult struct {
	EGraphDebugResult
	ValueState                            any              `json:"value_state,omitempty"`
	ResultCall                            *ResultCall      `json:"result_call,omitempty"`
	ResultCallRecipeDigest                string           `json:"result_call_recipe_digest,omitempty"`
	ResultCallRecipeDigestError           string           `json:"result_call_recipe_digest_error,omitempty"`
	ResultCallContentPreferredDigest      string           `json:"result_call_content_preferred_digest,omitempty"`
	ResultCallContentPreferredDigestError string           `json:"result_call_content_preferred_digest_error,omitempty"`
	ResultCallInputDigests                []string         `json:"result_call_input_digests,omitempty"`
	ResultCallInputDigestsError           string           `json:"result_call_input_digests_error,omitempty"`
	AssociatedTermIDs                     []uint64         `json:"associated_term_ids,omitempty"`
	IndexedDigests                        []string         `json:"indexed_digests,omitempty"`
	ExpiresAtUnix                         int64            `json:"expires_at_unix,omitempty"`
	CreatedAtUnixNano                     int64            `json:"created_at_unix_nano,omitempty"`
	LastUsedAtUnixNano                    int64            `json:"last_used_at_unix_nano,omitempty"`
	CacheUsageSizeByIdentity              map[string]int64 `json:"cache_usage_size_by_identity,omitempty"`
	PersistedEnvelopeKind                 string           `json:"persisted_envelope_kind,omitempty"`
	PersistedEnvelopeTypeName             string           `json:"persisted_envelope_type_name,omitempty"`
}

type CacheDebugResultDigestIndex added in v0.21.0 

type CacheDebugResultDigestIndex struct {
	Digest          string   `json:"digest"`
	SharedResultIDs []uint64 `json:"shared_result_ids"`
}

type CacheDebugSessionResults added in v0.21.0 

type CacheDebugSessionResults struct {
	SessionID       string   `json:"session_id"`
	SharedResultIDs []uint64 `json:"shared_result_ids"`
}

type CacheDebugSnapshot added in v0.21.0 

type CacheDebugSnapshot struct {
	OfferOwners             []CacheDebugOfferOwner        `json:"offer_owners,omitempty"`
	TraceFormatVersion      int                           `json:"trace_format_version"`
	BootID                  string                        `json:"boot_id"`
	EngineInstance          string                        `json:"engine_instance,omitempty"`
	CapturedAtSeq           uint64                        `json:"captured_at_seq"`
	CapturedAtTime          string                        `json:"captured_at_time"`
	SessionResults          []CacheDebugSessionResults    `json:"session_results,omitempty"`
	Results                 []CacheDebugResult            `json:"results"`
	ResultDigestIndexes     []CacheDebugResultDigestIndex `json:"result_digest_indexes"`
	Terms                   []EGraphDebugTerm             `json:"terms"`
	ResultTerms             []EGraphDebugResultTerm       `json:"result_terms"`
	Digests                 []EGraphDebugDigestMapping    `json:"digests"`
	EqClasses               []EGraphDebugEqClass          `json:"eq_classes"`
	OngoingCalls            []CacheDebugOngoingCall       `json:"ongoing_calls,omitempty"`
	OngoingArbitraryCalls   []CacheDebugArbitraryCall     `json:"ongoing_arbitrary_calls,omitempty"`
	CompletedArbitraryCalls []CacheDebugArbitraryCall     `json:"completed_arbitrary_calls,omitempty"`
}

CacheDebugSnapshot is the streamed /debug/dagql/cache snapshot.

EngineInstance names the engine instance that owns the cache, when the cache was given one: the service.instance.id of its telemetry.

type CacheDecision 

type CacheDecision struct {
	// Outcome is the call's cache outcome. Empty means the invocation never
	// reached a decision (e.g. it errored during validation or identity
	// derivation); nothing is stamped then.
	Outcome CacheOutcome

	// HitRoute is how the hit was found. Set only for Outcome == CacheOutcomeHit.
	HitRoute CacheHitRoute

	// MissIncompatibleCandidates records that the lookup's post-expiry
	// candidate set was non-empty but no candidate satisfied this session's
	// resource requirements. Meaningful only for misses (Outcome executed).
	MissIncompatibleCandidates bool

	// MissSawExpired records that TTL expiry eliminated at least one
	// otherwise-matching result during candidate accumulation. Meaningful only
	// for misses (Outcome executed).
	MissSawExpired bool

	// MissUnknownInputIndex is the index into StructuralInputs of the first
	// input digest that had no equivalence class at lookup time (making the
	// structural lookup impossible), or -1 when every input was known.
	// Meaningful only for misses (Outcome executed).
	MissUnknownInputIndex int

	// SelfDigest is the engine-derived structural self digest of the call.
	// Empty for CacheOutcomeUncached, whose path skips identity derivation.
	SelfDigest digest.Digest

	// StructuralInputs is the exact ordered structural-input digest list used
	// for the equivalence lookup (receiver, reference-valued arguments in
	// order, digest witnesses, module). Nil for CacheOutcomeUncached.
	StructuralInputs []digest.Digest

	// PairingDigest is the self digest derived with implicit inputs excluded —
	// the cross-run pairing anchor. Empty for CacheOutcomeUncached.
	PairingDigest digest.Digest
	// contains filtered or unexported fields
}

CacheDecision is the per-invocation cache-evidence carrier: a plain record of the decision facts for one GetOrInitCall invocation, filled by dagql along the existing control flow and consumed by core.AroundFunc's completion callback, which maps it onto the caller's already-existing span as the dagger.io/cache.* attribute vocabulary (engine/telemetryattrs).

Ownership: core allocates it onto CallRequest.CacheEvidence exactly when the call's span records and the call is not ProfileSkip-classified; dagql only ever fills a non-nil carrier (nil means "record nothing" and costs nothing). Every write happens on the invoking goroutine with values already in hand — the carrier adds no locking and never alters any cache decision. Population is best-effort: a fact whose derivation fails is dropped, never failing the call.

func NewCacheDecision 

func NewCacheDecision() *CacheDecision

NewCacheDecision returns an empty carrier with its index sentinel set.

func (*CacheDecision) ResultState 

func (ev *CacheDecision) ResultState(ctx context.Context, res AnyResult) (CacheResultState, bool)

ResultState reads res's state in the cache that decided this call, with the retention edge its publication adds while that is still to be created. It never waits on the cache's work, and reports false for a result the cache does not hold.

type CacheEntryStats added in v0.20.0 

type CacheEntryStats struct {
	OngoingCalls            int
	CompletedCalls          int
	RetainedCalls           int
	CompletedCallsByContent int
	OngoingArbitrary        int
	CompletedArbitrary      int
}

type CacheHitRoute 

type CacheHitRoute string

CacheHitRoute is how a cache hit was found. The values are the telemetryattrs.CacheHitRoute* wire tokens. 

const (
	CacheHitRouteRecipe     CacheHitRoute = telemetryattrs.CacheHitRouteRecipe
	CacheHitRouteDigest     CacheHitRoute = telemetryattrs.CacheHitRouteDigest
	CacheHitRouteStructural CacheHitRoute = telemetryattrs.CacheHitRouteStructural
)

type CacheID 

type CacheID string

CacheID is an engine cache's identity: the random ID its persistence database keeps across the engine's restarts.

type CacheIdentity 

type CacheIdentity struct {
	ID         string
	Generation uint64
}

CacheIdentity names a persistent cache across the engine processes that open it: ID is a random ID created with the cache's database, and Generation counts the opens of that database, 1 for the first.

func (CacheIdentity) String 

func (id CacheIdentity) String() string

String is the identity as telemetry carries it: "<ID>/<Generation>".

type CacheMetadataEstimate added in v0.21.9 

type CacheMetadataEstimate struct {
	ResultCount     int
	TermCount       int
	ClassSlotCount  int
	OfferOwnerCount int
	OfferOwnerBytes int64
	PayloadBytes    int64
	EstimatedBytes  int64
}

CacheMetadataEstimate is a coarse estimate of memory retained by the DAGQL cache's live results and symbolic graph. It models the existing result, term, and allocated eq-class cardinalities, plus the large byte payloads whose lengths values report through CachePayloadSizer.

type CacheMetadataPruneReport added in v0.21.9 

type CacheMetadataPruneReport struct {
	MaximumEstimatedBytes int64
	TargetEstimatedBytes  int64
	Triggered             bool

	BeforeCompaction       CacheMetadataEstimate
	AfterInitialCompaction CacheMetadataEstimate
	AfterPrune             CacheMetadataEstimate

	InitialCompactionOldClassSlots int
	InitialCompactionNewClassSlots int
	FinalCompactionOldClassSlots   int
	FinalCompactionNewClassSlots   int

	CandidateCount                int
	PlannedRootCount              int
	SimulatedCollectedResultCount int
	SimulatedStructuralBytes      int64
	RemovedPersistedRootCount     int
	CandidatesExhausted           bool
	// DroppedEdges are the retention edges the pass dropped, in order.
	DroppedEdges []CacheRetentionDrop
	// DroppedValues counts the values a blob-backed cache's pass dropped:
	// those that only holdings kept once their stored roots went.
	DroppedValues int

	SnapshotGCAttempted bool
	SnapshotGCSucceeded bool
	Duration            time.Duration
}

CacheMetadataPruneReport summarizes an automatic structural pruning pass. Unlike CachePruneReport, it never contains one entry per removed root.

type CacheOption 

type CacheOption func(*Cache)

CacheOption configures a Cache at construction.

func WithBlobStore 

func WithBlobStore() CacheOption

WithBlobStore marks the cache blob-backed: it accepts SetStoredPart. An engine's cache is not.

func WithEngineInstanceID 

func WithEngineInstanceID(id string) CacheOption

WithEngineInstanceID names the engine instance that owns the cache. The debug snapshot reports it as engine_instance.

func WithSnapshotShareReport 

func WithSnapshotShareReport(report func([]SnapshotSharedPart)) CacheOption

WithSnapshotShareReport makes the cache report, after each snapshot-sharing pass that completed parts, the parts it completed. Sharing runs outside any session, so no span reports them. report runs on the sharing worker with no cache lock held, and must not block.

type CacheOutcome 

type CacheOutcome string

CacheOutcome is what the cache decided for one call. The values are the telemetryattrs.CacheOutcome* wire tokens. 

const (
	CacheOutcomeHit      CacheOutcome = telemetryattrs.CacheOutcomeHit
	CacheOutcomeExecuted CacheOutcome = telemetryattrs.CacheOutcomeExecuted
	CacheOutcomeJoined   CacheOutcome = telemetryattrs.CacheOutcomeJoined
	CacheOutcomeUncached CacheOutcome = telemetryattrs.CacheOutcomeUncached
)

type CachePayloadSizer 

type CachePayloadSizer interface {
	CachePayloadBytes() int64
}

CachePayloadSizer is implemented by values that can retain a large in-memory byte payload, such as file contents held as a recipe, so the structural estimate can count it. CachePayloadBytes must be cheap: report lengths already at hand, never walk or serialize the value. The cache calls it once, outside its own locks, before the result is published.

type CachePersistenceResetReason added in v0.21.0 

type CachePersistenceResetReason string
const (
	CachePersistenceResetNone            CachePersistenceResetReason = ""
	CachePersistenceResetSchemaMismatch  CachePersistenceResetReason = "schema_mismatch"
	CachePersistenceResetUncleanShutdown CachePersistenceResetReason = "unclean_shutdown"
	CachePersistenceResetImportFailure   CachePersistenceResetReason = "import_failure"
)

type CachePrunePolicy added in v0.21.0 

type CachePrunePolicy struct {
	All           bool
	Filters       []string
	KeepDuration  time.Duration
	ReservedSpace int64
	MaxUsedSpace  int64
	MinFreeSpace  int64
	TargetSpace   int64

	// CurrentFreeSpace is optional available-disk bytes at prune start used to
	// evaluate MinFreeSpace. When unset, MinFreeSpace behaves as if free space
	// were zero.
	CurrentFreeSpace int64
}

type CachePruneReport added in v0.21.0 

type CachePruneReport struct {
	Entries        []CacheUsageEntry
	ReclaimedBytes int64
	// DroppedEdges are the retention edges the run dropped, in order.
	DroppedEdges []CacheRetentionDrop
	// DroppedValues counts the values a blob-backed cache's run dropped:
	// those that only holdings kept once their stored roots went.
	DroppedValues int
}

type CacheResultState 

type CacheResultState struct {
	// Deps are the result numbers of the entry's dependencies, sorted.
	Deps []uint64
	// Retained reports a retention edge, or one the call's publication adds,
	// expiring at RetentionExpiresAtUnix (0: never).
	Retained               bool
	RetentionExpiresAtUnix int64
	// ExpiresAtUnix is the entry's own expiry (0: none).
	ExpiresAtUnix int64
	// Parts are the part addresses of the entry's complete parts, sorted.
	Parts []string
	// Replacements counts the replacements of the entry's value in place;
	// the state above describes the current value.
	Replacements uint64
}

CacheResultState is the state of a cache entry in its cache, as a span reports it when it ends.

type CacheRetentionDrop 

type CacheRetentionDrop struct {
	ResultID  uint64
	DroppedAt time.Time
}

CacheRetentionDrop is one retention edge a prune run dropped: the entry's result number, and the engine's clock under the graph lock that deleted the edge. A run drops its edges one by one and releases the lock between them, so each drop has its own time.

type CacheUsageEntry added in v0.21.0 

type CacheUsageEntry struct {
	ID                        string
	Description               string
	RecordType                string
	RecordTypes               []string
	DagqlCall                 string
	SizeBytes                 int64
	CreatedTimeUnixNano       int64
	MostRecentUseTimeUnixNano int64
	ActivelyUsed              bool
}

type CacheUsageSizeProvider added in v0.21.1 

type CacheUsageSizeProvider interface {
	SnapshotSize(context.Context, string) (int64, error)
}

CacheUsageSizeProvider resolves concrete snapshot sizes for cache usage accounting.

type CallPayloadSeenKeyStore 

type CallPayloadSeenKeyStore interface {
	ClaimCallPayload(string) bool
}

CallPayloadSeenKeyStore tracks immutable call payload delivery per target in the current route — the emitting client and its ancestors, i.e. the DBs its telemetry fans out to. The engine hands producers a store scoped to that route rather than to the session, so a claim never outlives the set of clients the payload was actually delivered to; a client attaching later still receives every frame on its first closure walk.

ClaimCallPayload reports whether the payload for a digest still has to be delivered to ANY target on the route, CLAIMING those targets for the caller when so. It returns true at most once per digest per target until the claim is released, so concurrent closure walks over a shared chain build and encode each frame once rather than once per walk. The claimant then delivers the frame on exactly one carrier — its recording span's dagger.io/dag.call attribute, or a payload log record — and the engine's exporter for that carrier settles the claim per target after persistence: a successful write marks the target delivered for good, a failed one releases it so a retry or a later walk can repair the gap.

Unlike ShouldEmitTelemetry this is deliberately NOT sensitive to WithRepeatedTelemetry or to DoNotCache. Both exist so the same work can be SHOWN again — a re-run tool call is a new span worth seeing — but a payload is immutable data keyed by its own digest, so a second copy tells a client nothing it does not already have.

type CallRequest added in v0.21.0 

type CallRequest struct {
	*ResultCall

	ConcurrencyKey string
	TTL            int64
	DoNotCache     bool
	IsPersistable  bool

	// ListItem marks a read of item Nth of the receiver, a cache-backed list
	// whose value holds the item inline. Such a read is answered only by the
	// item the receiver recorded for that position (sharedResult.listItems):
	// two entries of one list recipe can hold different values, and so can a
	// transferred item whose list the cache did not take, so items matched
	// by recipe could assemble a list that is neither.
	ListItem bool

	// PassthroughTelemetry keeps the call span available for trace metadata while
	// asking the UI to show its children in its place.
	PassthroughTelemetry bool

	// ReceiverTypeName is the immediate receiver's GraphQL type name, stamped
	// lookup-free at the object call site (objects.go) from r.class.inner.Type().Name().
	// It is request-only carrier state (never digested, never persisted) consumed by
	// core.AroundFunc to compute the static profile-skip decision and stamp it onto
	// the call frame (ResultCall.ProfileSkip) — so the predicate needs no egraphMu
	// receiver-resolution lookup per call.
	ReceiverTypeName string

	// CacheEvidence is the per-invocation cache-decision evidence carrier.
	// Like ReceiverTypeName it is request-only carrier state (never digested,
	// never persisted); unlike ReceiverTypeName it is additionally scoped to a
	// single invocation and therefore deliberately omitted by Clone — a cloned
	// request is a different (or internal) invocation and must not share the
	// record. core.AroundFunc allocates it exactly when this call's span
	// records and the call is not ProfileSkip-classified; getOrInitCallInner
	// fills it along the existing decision flow; AroundFunc's completion
	// callback stamps it onto the caller's span. Nil means "record nothing" —
	// internal CallRequest constructions that never pass through AroundFunc
	// leave it nil.
	CacheEvidence *CacheDecision
}

CallRequest is the mutable planning-time wrapper around the semantic ResultCall shape, plus request-only cache policy that does not belong in persisted provenance.

func (*CallRequest) Arg added in v0.21.0 

func (req *CallRequest) Arg(name string) *ResultCallArg

func (*CallRequest) Clone added in v0.21.0 

func (req *CallRequest) Clone() *CallRequest

func (*CallRequest) DeleteArg added in v0.21.0 

func (req *CallRequest) DeleteArg(name string)

func (*CallRequest) HasArg added in v0.21.0 

func (req *CallRequest) HasArg(name string) bool

func (*CallRequest) SetArg added in v0.21.0 

func (req *CallRequest) SetArg(arg *ResultCallArg)

func (*CallRequest) SetArgInput added in v0.21.0 

func (req *CallRequest) SetArgInput(ctx context.Context, name string, input Input, sensitive bool) error

func (*CallRequest) SetImplicitInput 

func (req *CallRequest) SetImplicitInput(ctx context.Context, name string, input Input) error

SetImplicitInput adds an engine-computed input to the call's identity. Unlike an argument, the resolver does not receive it and call displays omit it.

func (*CallRequest) ToResultCall added in v0.21.0 

func (req *CallRequest) ToResultCall() (*ResultCall, error)

type CapturedCodecOutput 

type CapturedCodecOutput struct {
	Address PersistedPartAddress
	State   string
	// ValueKind remains known when pending output metadata is not yet known.
	ValueKind  string
	Value      *SnapshotValue
	Role       string
	SnapshotID string
}

type Class 

type Class[T Typed] struct {
	// contains filtered or unexported fields
}

Class is a class of Object types.

The class is defined by a set of fields, which are installed into the class dynamically at runtime.

func NewClass 

func NewClass[T Typed](srv *Server, opts_ ...ClassOpts[T]) Class[T]

NewClass returns a new empty class for a given type.

func (Class[T]) Extend 

func (class Class[T]) Extend(spec FieldSpec, fun FieldFunc)

func (Class[T]) Field 

func (class Class[T]) Field(name string, view call.View) (Field[T], bool)

func (Class[T]) FieldSpec added in v0.16.2 

func (class Class[T]) FieldSpec(name string, view call.View) (FieldSpec, bool)

func (Class[T]) FieldSpecs added in v0.20.4 

func (class Class[T]) FieldSpecs(view call.View) []FieldSpec

func (Class[T]) ForkObjectType added in v0.21.0 

func (class Class[T]) ForkObjectType(srv *Server) (ObjectType, error)

func (Class[T]) IDType 

func (class Class[T]) IDType() (IDType, bool)

func (Class[T]) ImplementInterface added in v0.21.1 

func (class Class[T]) ImplementInterface(iface *Interface)

ImplementInterface is the same as Implements but satisfies the InterfaceImplementor interface for use via the ObjectType interface.

func (Class[T]) ImplementInterfaceUnchecked added in v0.21.1 

func (class Class[T]) ImplementInterfaceUnchecked(iface *Interface)

ImplementInterfaceUnchecked declares interface conformance without performing the dagql structural Satisfies check. Use this when a higher-level type system (e.g. core's IsSubtypeOf) has already validated conformance.

func (Class[T]) Implements added in v0.21.1 

func (class Class[T]) Implements(iface *Interface)

Implements declares that this class implements the given interface.

It verifies that the class structurally satisfies the interface (has all required fields with compatible types). If not, it panics — this is a programming error, like a bad field type.

The check uses the empty view ("") which sees all global fields.

func (Class[T]) Install 

func (class Class[T]) Install(fields ...Field[T])

func (Class[T]) Interfaces added in v0.21.1 

func (class Class[T]) Interfaces() []*Interface

Interfaces returns the interfaces this class implements.

func (Class[T]) New 

func (class Class[T]) New(val AnyResult) (AnyObjectResult, error)

New returns a new instance of the class.

func (Class[T]) ParseField 

func (class Class[T]) ParseField(ctx context.Context, view call.View, astField *ast.Field, vars map[string]any) (Selector, *ast.Type, error)

ParseField parses a field selection into a Selector and return type.

func (Class[T]) TypeDefinition 

func (class Class[T]) TypeDefinition(view call.View) *ast.Definition

TypeDefinition returns the schema definition of the class.

The definition is derived from the type name, description, and fields. The type may implement Definitive or Descriptive to provide more information.

Each currently defined field is installed on the returned definition.

func (Class[T]) TypeName 

func (class Class[T]) TypeName() string

func (Class[T]) Typed 

func (class Class[T]) Typed() Typed

func (Class[T]) View added in v0.21.9 

func (class Class[T]) View(view ViewFilter) Class[T]

func (Class[T]) ViewFilter added in v0.21.9 

func (class Class[T]) ViewFilter() ViewFilter

type ClassOpts 

type ClassOpts[T Typed] struct {
	// NoIDs disables the default "id" field and disables the IDType method.
	NoIDs bool

	// Typed contains the Typed value whose Type() determines the class's type.
	//
	// In the simple case, we can just use a zero-value, but it is also allowed
	// to use a dynamic Typed value.
	Typed T

	// The inner type sourceMap directive so additional type
	// registered by the engine can store also store its origin.
	SourceMap *ast.Directive

	// View limits the object type and its generated ID/load fields to a schema view.
	View ViewFilter
}

type CloudPartOffer 

type CloudPartOffer struct {
	Offer PersistedPartOffer
	// CloudNumber is the counterpart's number in the Cloud cache.
	CloudNumber uint64
	// CloudStored is whether the counterpart stores a record. It may not:
	// the Cloud can offer a part it keeps for another entry of the class.
	CloudStored bool
	// CloudExpiresAtUnix is the stored record's expiry, 0 for none. It is
	// ignored when the counterpart stores no record.
	CloudExpiresAtUnix int64
}

CloudPartOffer is one part the Cloud offers an engine: the offer, and the Cloud counterpart of the entry the offer's address resolves to, the receiver or one of its descendants. A part borrowed from another entry of the Cloud's class still names that counterpart, not the donor. The entry keeps the counterpart as its Cloud holding.

type DecoderFunc 

type DecoderFunc func(any) (Input, error)

func (DecoderFunc) DecodeInput 

func (f DecoderFunc) DecodeInput(val any) (Input, error)

type Definitive 

type Definitive interface {
	TypeDefinition(view call.View) *ast.Definition
}

Definitive is a type that knows how to define itself in the schema.

type DependencyResult added in v0.21.0 

type DependencyResult struct {
	Result AnyResult
	// Owned is true when the parent's install span should also be attributed
	// to this dep for lazy failure causality. False marks the edge as
	// liveness-only — the dep is kept alive by the parent and preflighted
	// before the parent's lazy callback, but failures in the dep do not
	// short-circuit attribution onto the parent's install span.
	Owned bool
}

DependencyResult is an attached dependency result with a kind flag.

type Derefable 

type Derefable interface {
	Deref() (Typed, bool)
}

Derefable is a type that wraps another type.

In practice this is only used for Optional and Nullable. It should be used sparingly, since wrapping interfaces explodes very quickly.

type DerefableResult added in v0.18.13 

type DerefableResult interface {
	Derefable
	DerefToResult(call *ResultCall) (AnyResult, bool)
}

DerefableResult is a Derefable that can return a result underlied by the specific type the Derefable wraps.

type Descriptive 

type Descriptive interface {
	TypeDescription() string
}

Descriptive is an interface for types that have a description.

The description is used in the schema. To provide a full definition, implement Definitive instead.

type DigestedSerializedString added in v0.21.0 

type DigestedSerializedString[T any] struct {
	Self   T
	Digest digest.Digest
}

func NewDigestedSerializedString added in v0.21.0 

func NewDigestedSerializedString[T any](val T, dig digest.Digest) DigestedSerializedString[T]

func (DigestedSerializedString[T]) DecodeInput added in v0.21.0 

func (DigestedSerializedString[T]) DecodeInput(val any) (Input, error)

func (DigestedSerializedString[T]) Decoder added in v0.21.0 

func (s DigestedSerializedString[T]) Decoder() InputDecoder

func (DigestedSerializedString[T]) MarshalJSON added in v0.21.0 

func (s DigestedSerializedString[T]) MarshalJSON() ([]byte, error)

func (DigestedSerializedString[T]) SetField added in v0.21.0 

func (s DigestedSerializedString[T]) SetField(v reflect.Value) error

func (DigestedSerializedString[T]) String added in v0.21.0 

func (s DigestedSerializedString[T]) String() string

func (DigestedSerializedString[T]) ToLiteral added in v0.21.0 

func (s DigestedSerializedString[T]) ToLiteral() call.Literal

func (DigestedSerializedString[T]) Type added in v0.21.0 

func (DigestedSerializedString[T]) Type() *ast.Type

func (*DigestedSerializedString[T]) UnmarshalJSON added in v0.21.0 

func (s *DigestedSerializedString[T]) UnmarshalJSON(p []byte) error

type DirectiveLocation 

type DirectiveLocation string

func (DirectiveLocation) Decoder 

func (DirectiveLocation) Decoder() InputDecoder

func (DirectiveLocation) ToLiteral 

func (d DirectiveLocation) ToLiteral() call.Literal

func (DirectiveLocation) Type 

func (DirectiveLocation) Type() *ast.Type

type DirectiveSpec 

type DirectiveSpec struct {
	Name         string              `field:"true"`
	Description  string              `field:"true"`
	Args         InputSpecs          `field:"true"`
	Locations    []DirectiveLocation `field:"true"`
	IsRepeatable bool                `field:"true"`

	// ViewFilter is a filter that specifies under which views this directive
	// is visible.
	ViewFilter ViewFilter
}

func (DirectiveSpec) DirectiveDefinition 

func (d DirectiveSpec) DirectiveDefinition(view call.View) *ast.DirectiveDefinition

func (DirectiveSpec) View 

func (d DirectiveSpec) View(filter ViewFilter) DirectiveSpec

View sets the ViewFilter under which this directive is visible.

type DrainTicket 

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

func (*DrainTicket) Wait 

func (drain *DrainTicket) Wait(ctx context.Context) error

type DynamicArrayInput 

type DynamicArrayInput struct {
	Elem   Input
	Values []Input
}

func (DynamicArrayInput) DecodeInput 

func (d DynamicArrayInput) DecodeInput(val any) (Input, error)

func (DynamicArrayInput) Decoder 

func (d DynamicArrayInput) Decoder() InputDecoder

func (DynamicArrayInput) Element added in v0.16.3 

func (d DynamicArrayInput) Element() Typed

func (DynamicArrayInput) Len 

func (d DynamicArrayInput) Len() int

func (DynamicArrayInput) Nth 

func (d DynamicArrayInput) Nth(i int) (Typed, error)

func (DynamicArrayInput) NthValue added in v0.18.13 

func (d DynamicArrayInput) NthValue(i int, call *ResultCall) (AnyResult, error)

func (DynamicArrayInput) SetField 

func (d DynamicArrayInput) SetField(val reflect.Value) error

func (DynamicArrayInput) ToLiteral 

func (d DynamicArrayInput) ToLiteral() call.Literal

func (DynamicArrayInput) Type 

func (d DynamicArrayInput) Type() *ast.Type

type DynamicArrayOutput 

type DynamicArrayOutput struct {
	Elem   Typed
	Values []Typed
}

func (DynamicArrayOutput) Element added in v0.16.3 

func (d DynamicArrayOutput) Element() Typed

func (DynamicArrayOutput) Len 

func (d DynamicArrayOutput) Len() int

func (DynamicArrayOutput) MarshalJSON 

func (d DynamicArrayOutput) MarshalJSON() ([]byte, error)

func (DynamicArrayOutput) Nth 

func (d DynamicArrayOutput) Nth(i int) (Typed, error)

func (DynamicArrayOutput) NthValue added in v0.18.13 

func (d DynamicArrayOutput) NthValue(i int, call *ResultCall) (AnyResult, error)

func (DynamicArrayOutput) SetField added in v0.9.9 

func (d DynamicArrayOutput) SetField(val reflect.Value) error

func (DynamicArrayOutput) Type 

func (d DynamicArrayOutput) Type() *ast.Type

type DynamicInputFunc added in v0.21.0 

type DynamicInputFunc[T Typed, A any] func(
	context.Context,
	ObjectResult[T],
	A,
	*CallRequest,
) error

type DynamicNullable 

type DynamicNullable struct {
	Elem  Typed
	Value Typed
	Valid bool
}

func (DynamicNullable) Deref 

func (n DynamicNullable) Deref() (Typed, bool)

func (DynamicNullable) DerefToResult added in v0.18.13 

func (n DynamicNullable) DerefToResult(
	call *ResultCall,
) (AnyResult, bool)

func (DynamicNullable) MarshalJSON 

func (n DynamicNullable) MarshalJSON() ([]byte, error)

func (DynamicNullable) Type 

func (n DynamicNullable) Type() *ast.Type

func (*DynamicNullable) UnmarshalJSON 

func (n *DynamicNullable) UnmarshalJSON(p []byte) error

type DynamicOptional 

type DynamicOptional struct {
	Elem  Input
	Value Input
	Valid bool
}

func (DynamicOptional) DecodeInput 

func (o DynamicOptional) DecodeInput(val any) (Input, error)

func (DynamicOptional) Decoder 

func (o DynamicOptional) Decoder() InputDecoder

func (DynamicOptional) Deref 

func (o DynamicOptional) Deref() (Typed, bool)

func (DynamicOptional) MarshalJSON 

func (o DynamicOptional) MarshalJSON() ([]byte, error)

func (DynamicOptional) SetField 

func (o DynamicOptional) SetField(val reflect.Value) error

func (DynamicOptional) ToLiteral 

func (o DynamicOptional) ToLiteral() call.Literal

func (DynamicOptional) Type 

func (o DynamicOptional) Type() *ast.Type

func (*DynamicOptional) UnmarshalJSON added in v0.21.0 

func (o *DynamicOptional) UnmarshalJSON(p []byte) error

func (DynamicOptional) Unwrap added in v0.19.7 

func (o DynamicOptional) Unwrap() Typed

type DynamicResultArrayOutput added in v0.18.13 

type DynamicResultArrayOutput struct {
	Elem   Typed
	Values []AnyResult
}

func (DynamicResultArrayOutput) AttachDependencyResults added in v0.21.0 

func (d DynamicResultArrayOutput) AttachDependencyResults(
	_ context.Context,
	_ AnyResult,
	attach func(AnyResult) (AnyResult, error),
) ([]AnyResult, error)

func (DynamicResultArrayOutput) Element added in v0.18.13 

func (d DynamicResultArrayOutput) Element() Typed

func (DynamicResultArrayOutput) Len added in v0.18.13 

func (d DynamicResultArrayOutput) Len() int

func (DynamicResultArrayOutput) MarshalJSON added in v0.18.13 

func (d DynamicResultArrayOutput) MarshalJSON() ([]byte, error)

func (DynamicResultArrayOutput) Nth added in v0.18.13 

func (d DynamicResultArrayOutput) Nth(i int) (Typed, error)

func (DynamicResultArrayOutput) NthValue added in v0.18.13 

func (d DynamicResultArrayOutput) NthValue(i int, _ *ResultCall) (AnyResult, error)

func (DynamicResultArrayOutput) SetField added in v0.18.13 

func (d DynamicResultArrayOutput) SetField(val reflect.Value) error

func (DynamicResultArrayOutput) Type added in v0.18.13 

func (d DynamicResultArrayOutput) Type() *ast.Type

type EGraphDebugDigestMapping added in v0.21.0 

type EGraphDebugDigestMapping struct {
	Digest    string `json:"digest"`
	EqClassID uint64 `json:"eq_class_id"`
}

type EGraphDebugEqClass added in v0.21.0 

type EGraphDebugEqClass struct {
	EqClassID uint64   `json:"eq_class_id"`
	Digests   []string `json:"digests"`
}

type EGraphDebugInputProvenance added in v0.21.0 

type EGraphDebugInputProvenance struct {
	Kind string `json:"kind"`
}

type EGraphDebugResult added in v0.21.0 

type EGraphDebugResult struct {
	SharedResultID             uint64                     `json:"shared_result_id"`
	OutputEqClassIDs           []uint64                   `json:"output_eq_class_ids,omitempty"`
	RecordType                 string                     `json:"record_type,omitempty"`
	Description                string                     `json:"description,omitempty"`
	TypeName                   string                     `json:"type_name,omitempty"`
	IncomingOwnershipCount     int64                      `json:"incoming_ownership_count"`
	HasValue                   bool                       `json:"has_value"`
	PayloadState               string                     `json:"payload_state"`
	HasPersistedEdge           bool                       `json:"has_persisted_edge"`
	PersistedEdgeUnpruneable   bool                       `json:"persisted_edge_unpruneable"`
	PersistedEdgeExpiresAtUnix int64                      `json:"persisted_edge_expires_at_unix,omitempty"`
	Replacements               uint64                     `json:"replacements,omitempty"`
	Indexed                    bool                       `json:"indexed,omitempty"`
	ExplicitDeps               []uint64                   `json:"explicit_dep_ids,omitempty"`
	HeldDependencyResults      int                        `json:"held_dependency_results_count"`
	SnapshotLinks              []PersistedSnapshotRefLink `json:"snapshot_links,omitempty"`
}

EGraphDebugResult describes one result. PersistedEdgeExpiresAtUnix is the retention edge's own expiry (0: none), distinct from the result's expiry.

type EGraphDebugResultTerm added in v0.21.0 

type EGraphDebugResultTerm struct {
	SharedResultID  uint64                       `json:"shared_result_id"`
	TermID          uint64                       `json:"term_id"`
	InputProvenance []EGraphDebugInputProvenance `json:"input_provenance,omitempty"`
}

type EGraphDebugSnapshot added in v0.21.0 

type EGraphDebugSnapshot struct {
	OfferOwners        []CacheDebugOfferOwner     `json:"offer_owners,omitempty"`
	TraceFormatVersion int                        `json:"trace_format_version"`
	BootID             string                     `json:"boot_id"`
	CapturedAtSeq      uint64                     `json:"captured_at_seq"`
	CapturedAtTime     string                     `json:"captured_at_time"`
	Results            []EGraphDebugResult        `json:"results"`
	Terms              []EGraphDebugTerm          `json:"terms"`
	ResultTerms        []EGraphDebugResultTerm    `json:"result_terms"`
	Digests            []EGraphDebugDigestMapping `json:"digests"`
	EqClasses          []EGraphDebugEqClass       `json:"eq_classes"`
}

type EGraphDebugTerm added in v0.21.0 

type EGraphDebugTerm struct {
	TermID     uint64   `json:"term_id"`
	SelfDigest string   `json:"self_digest"`
	InputEqIDs []uint64 `json:"input_eq_ids"`
	TermDigest string   `json:"term_digest"`
	OutputEqID uint64   `json:"output_eq_id"`
}

type EnumValue 

type EnumValue[T enumValue] struct {
	Value       T
	Underlying  T
	Description string
	View        ViewFilter
}

type EnumValueName added in v0.13.6 

type EnumValueName struct {
	Enum string
	Name string
}

func (*EnumValueName) DecodeInput added in v0.13.6 

func (e *EnumValueName) DecodeInput(val any) (Input, error)

func (*EnumValueName) Decoder added in v0.13.6 

func (e *EnumValueName) Decoder() InputDecoder

func (*EnumValueName) MarshalJSON added in v0.13.6 

func (e *EnumValueName) MarshalJSON() ([]byte, error)

func (*EnumValueName) ToLiteral added in v0.13.6 

func (e *EnumValueName) ToLiteral() call.Literal

func (*EnumValueName) Type added in v0.13.6 

func (e *EnumValueName) Type() *ast.Type

func (*EnumValueName) TypeDefinition added in v0.13.6 

func (e *EnumValueName) TypeDefinition(view call.View) *ast.Definition

func (*EnumValueName) TypeName added in v0.13.6 

func (e *EnumValueName) TypeName() string

type EnumValues 

type EnumValues[T enumValue] []EnumValue[T]

EnumValues is a list of possible values for an Enum.

func NewEnum 

func NewEnum[T enumValue](vals ...T) *EnumValues[T]

NewEnum creates a new EnumType with the given possible values.

func (*EnumValues[T]) Alias added in v0.18.11 

func (e *EnumValues[T]) Alias(val T, target T) T

func (*EnumValues[T]) AliasView added in v0.18.11 

func (e *EnumValues[T]) AliasView(val T, target T, view ViewFilter) T

func (*EnumValues[T]) DecodeInput 

func (e *EnumValues[T]) DecodeInput(val any) (Input, error)

func (*EnumValues[T]) Install 

func (e *EnumValues[T]) Install(srv *Server, filter ...ViewFilter)

func (*EnumValues[T]) Literal 

func (e *EnumValues[T]) Literal(val T) call.Literal

func (*EnumValues[T]) Lookup 

func (e *EnumValues[T]) Lookup(val string) (T, error)

func (*EnumValues[T]) PossibleValues 

func (e *EnumValues[T]) PossibleValues(view call.View) ast.EnumValueList

func (*EnumValues[T]) Register 

func (e *EnumValues[T]) Register(val T, desc ...string) T

func (*EnumValues[T]) RegisterView added in v0.18.11 

func (e *EnumValues[T]) RegisterView(val T, view ViewFilter, desc ...string) T

func (*EnumValues[T]) Type 

func (e *EnumValues[T]) Type() *ast.Type

func (*EnumValues[T]) TypeDefinition 

func (e *EnumValues[T]) TypeDefinition(view call.View) *ast.Definition

func (*EnumValues[T]) TypeName 

func (e *EnumValues[T]) TypeName() string

type Enumerable 

type Enumerable interface {
	// Element returns the element of the Enumerable.
	Element() Typed
	// Len returns the number of elements in the Enumerable.
	Len() int
	// Nth returns the Nth element of the Enumerable, with 1 representing the
	// first entry.
	Nth(int) (Typed, error)

	NthValue(i int, call *ResultCall) (AnyResult, error)
}

Enumerable is a value that has a length and allows indexing.

type ExactView added in v0.12.0 

type ExactView string

ExactView contains exactly one view.

func (ExactView) Contains added in v0.12.0 

func (exact ExactView) Contains(view call.View) bool

type ExportedValues 

type ExportedValues struct {
	Bundle ValueBundle
	Chains *SelectedChains
	// ChainTime is the wall time spent opening the selected chains, which
	// may compress a layer the first time it is exported.
	ChainTime time.Duration
	// Sources maps bundle ordinals to held source rows; it is not transported.
	Sources []ImportedValue
}

type ExtendedError 

type ExtendedError interface {
	error
	Extensions() map[string]any
}

ExtendedError is an error that can provide extra data in an error response.

type Field 

type Field[T Typed] struct {
	Spec *FieldSpec
	Func func(context.Context, ObjectResult[T], map[string]Input, call.View) (AnyResult, error)
}

Field defines a field of an Object type.

func Func 

func Func[T Typed, A any, R any](name string, fn FuncHandler[T, A, R]) Field[T]

Func is a helper for defining a field resolver and schema.

The function must accept a context.Context, the receiver, and a struct of arguments. All fields of the arguments struct must be Typed so that the schema may be derived, and Scalar to ensure a default value may be provided.

Arguments use struct tags to further configure the schema:

  • `name:"bar"` sets the name of the argument. By default this is the toLowerCamel'd field name.
  • `default:"foo"` sets the default value of the argument. The Scalar type determines how this value is parsed.
  • `doc:"..."` sets the description of the argument.

The function must return a Typed value, and an error.

To configure a description for the field in the schema, call .Doc on the result.

func FuncWithDynamicInputs added in v0.21.0 

func FuncWithDynamicInputs[T Typed, A any, R any](
	name string,
	fn FuncHandler[T, A, R],
	cacheFn DynamicInputFunc[T, A],
) Field[T]

FuncWithDynamicInputs is like Func but lets a resolver customize request/cache behavior for each call (for example argument rewrites, TTL, do-not-cache, or concurrency key).

func NodeFunc 

func NodeFunc[T Typed, A any, R any](name string, fn NodeFuncHandler[T, A, R]) Field[T]

NodeFunc is the same as Func, except it passes the ObjectResult instead of the receiver so that you can access its ID.

func NodeFuncWithDynamicInputs added in v0.21.0 

func NodeFuncWithDynamicInputs[T Typed, A any, R any](
	name string,
	fn NodeFuncHandler[T, A, R],
	cacheFn DynamicInputFunc[T, A],
) Field[T]

NodeFuncWithDynamicInputs is like NodeFunc but lets a resolver customize request/cache behavior for each call (for example argument rewrites, TTL, do-not-cache, or concurrency key).

func (Field[T]) Args added in v0.18.6 

func (field Field[T]) Args(args ...Argument) Field[T]

func (Field[T]) Deprecated 

func (field Field[T]) Deprecated(paras ...string) Field[T]

Deprecated marks the field as deprecated, meaning it should not be used by new code.

func (Field[T]) DoNotCache added in v0.16.3 

func (field Field[T]) DoNotCache(reason string, paras ...string) Field[T]

DoNotCache marks the field as not to be stored in the cache for the given reason why

func (Field[T]) Doc 

func (field Field[T]) Doc(paras ...string) Field[T]

Doc sets the description of the field. Each argument is joined by two empty lines.

func (Field[T]) Experimental added in v0.18.4 

func (field Field[T]) Experimental(paras ...string) Field[T]

Deprecated marks the field as experimental

func (Field[T]) Extend added in v0.12.0 

func (field Field[T]) Extend() Field[T]

func (Field[T]) FieldDefinition 

func (field Field[T]) FieldDefinition(view call.View) *ast.FieldDefinition

FieldDefinition returns the schema definition of the field.

func (Field[T]) IsPersistable added in v0.21.0 

func (field Field[T]) IsPersistable() Field[T]

func (Field[T]) NotReplayable 

func (field Field[T]) NotReplayable(reason string) Field[T]

NotReplayable marks a field for structural recipe classification and rejection by LoadReplayable. It does not affect ordinary recipe evaluation or caching.

func (Field[T]) PassthroughTelemetry 

func (field Field[T]) PassthroughTelemetry() Field[T]

func (Field[T]) Sensitive added in v0.16.2 

func (field Field[T]) Sensitive() Field[T]

func (Field[T]) View added in v0.12.0 

func (field Field[T]) View(view ViewFilter) Field[T]

View sets a view for this field.

func (Field[T]) WithInput added in v0.21.0 

func (field Field[T]) WithInput(inputs ...ImplicitInput) Field[T]

type FieldFunc 

type FieldFunc func(context.Context, AnyResult, map[string]Input) (AnyResult, error)

FieldFunc is a function that implements a field on an object while limited to the object's external interface.

type FieldModuleProvider 

type FieldModuleProvider func(ctx context.Context, srv *Server) (*ResultCallModule, error)

FieldModuleProvider supplies the module provenance for one call to a field. It runs while the call is prepared, with the calling context and the server the selection was made through, and returns a result-backed module reference that is valid in the calling session.

Contract: a schema can outlive the session that installed it, so the provider must not capture that session or any result only that session owns. It may rely only on results the field's holder keeps alive (for module classes, the operational module that every cached module object and tool binding owns explicitly) and on results it acquires in the calling session.

type FieldSpec 

type FieldSpec struct {
	// Name is the name of the field.
	Name string
	// Description is the description of the field.
	Description string
	// Args is the list of arguments that the field accepts.
	Args InputSpecs
	// Type is the type of the field's result.
	Type Typed
	// Sensitive indicates that the value returned by this field is sensitive and
	// should not be displayed in telemetry.
	Sensitive bool
	// DeprecatedReason deprecates the field and provides a reason.
	DeprecatedReason *string
	// ExperimentalReason marks the field as experimental and provides a reason.
	ExperimentalReason string
	// Module is frame-native provenance for the module that provides the field's
	// implementation. When ModuleProvider is set it only describes the module
	// (name, ref, pin) statically and carries no result reference.
	Module *ResultCallModule
	// ModuleProvider, if set, supplies the module's result reference each time
	// a call to the field is prepared, in the calling session. See
	// FieldModuleProvider for the contract.
	ModuleProvider FieldModuleProvider
	// Directives is the list of GraphQL directives attached to this field.
	Directives []*ast.Directive

	// ViewFilter is filter that specifies under which views this field is
	// accessible. If not view is present, the default is the "global" view.
	ViewFilter ViewFilter

	// If set, the result of this field will never be cached and not have concurrent equal
	// calls deduped. The string value is a reason why the field should not be cached.
	DoNotCache string

	// If set, the result of this field will be cached for the given TTL (in seconds).
	TTL int64

	// If set, the result of this field is eligible for persistent cache storage.
	IsPersistable bool

	// If set, this GetDynamicInput will be called before cache evaluation to
	// make any dynamic adjustments to the call request or its policy.
	GetDynamicInput GenericDynamicInputFunc

	// ImplicitInputs are engine-computed inputs that are attached to the call
	// identity but are not explicit GraphQL field args.
	ImplicitInputs []ImplicitInput

	// NotReplayable identifies fields that require the originating client or
	// explicit authorization. ClassifyRecipe reports this metadata and
	// LoadReplayable enforces it; ordinary loading and caching are unchanged.
	NotReplayable string

	// NoTelemetry suppresses telemetry (AroundFunc) for this field.
	// Used for entrypoint proxies that delegate to real fields which
	// emit their own telemetry.
	NoTelemetry bool

	// Trivial marks fields that only unwrap data from their receiver rather
	// than performing meaningful work. Their telemetry spans are internal, and
	// they skip install-span capture so they don't claim ownership of values
	// they merely return.
	Trivial bool

	// PassthroughTelemetry keeps this field's telemetry span available for call
	// metadata while asking the UI to show its children in its place.
	PassthroughTelemetry bool
	// contains filtered or unexported fields
}

FieldSpec is a specification for a field.

func (FieldSpec) FieldDefinition 

func (spec FieldSpec) FieldDefinition(view call.View) *ast.FieldDefinition

type Fields 

type Fields[T Typed] []Field[T]

Fields defines a set of fields for an Object type.

func (Fields[T]) Install 

func (fields Fields[T]) Install(server *Server)

Install installs the field's Object type if needed, and installs all fields into the type.

type Float 

type Float float64

Float is a GraphQL Float scalar.

func NewFloat 

func NewFloat[T constraints.Float](val T) Float

func (Float) DecodeInput 

func (Float) DecodeInput(val any) (Input, error)

func (Float) Decoder 

func (Float) Decoder() InputDecoder

func (Float) Float64 

func (f Float) Float64() float64

func (Float) MarshalJSON 

func (f Float) MarshalJSON() ([]byte, error)

func (Float) SetField 

func (f Float) SetField(v reflect.Value) error

func (Float) ToLiteral 

func (f Float) ToLiteral() call.Literal

func (Float) Type 

func (Float) Type() *ast.Type

func (Float) TypeDefinition 

func (f Float) TypeDefinition(view call.View) *ast.Definition

func (Float) TypeName 

func (Float) TypeName() string

func (*Float) UnmarshalJSON 

func (f *Float) UnmarshalJSON(p []byte) error

type ForeignPayload 

type ForeignPayload struct{ JSON json.RawMessage }

type ForkableObjectType added in v0.21.0 

type ForkableObjectType interface {
	ForkObjectType(*Server) (ObjectType, error)
}

ForkableObjectType is an installed object type that can be safely cloned into another server without sharing mutable server-bound state like field tables or schema-cache invalidation callbacks.

type FuncHandler added in v0.16.3 

type FuncHandler[T Typed, A any, R any] func(ctx context.Context, self T, args A) (R, error)

type GateOutcome 

type GateOutcome uint8
const (
	GateGranted GateOutcome = iota
	GateBusy
	GateAlreadyInstalled
	GateExecutionStarted
	GateReselect
)

type GenericDynamicInputFunc added in v0.21.0 

type GenericDynamicInputFunc func(
	context.Context,
	AnyResult,
	map[string]Input,
	call.View,
	*CallRequest,
) error

type HasDecodedDependencyResults 

type HasDecodedDependencyResults interface {
	DecodedDependencyResults() []AnyResult
}

HasDecodedDependencyResults is implemented by decoded object payloads that capture attached results supplied by the decoding server rather than by the persisted bytes (for example the module a module object class was installed from). Such results are owned only by the decoding session, while the decoded payload lives as long as its row. When a decoded payload is installed on its row, the cache adds an ordinary explicit dependency edge from the row to each attached result returned here, before the payload is published, so the row retains them. A detached result here is an error: it cannot be owned, so the decode fails rather than install a payload that outlives what it captured. Dependency attachment hooks are not rerun for decoded payloads.

type HasDependencyResults added in v0.21.0 

type HasDependencyResults interface {
	AttachDependencyResults(context.Context, AnyResult, func(AnyResult) (AnyResult, error)) ([]AnyResult, error)
}

HasDependencyResults is implemented by resolver-returned values that embed dependency results which must be normalized onto attached/cache-backed results before lifecycle bookkeeping or persistence.

Implementations must:

  • use self when they need to rewrite internal references to the attached owner result itself
  • call attach for each embedded child result that should be normalized
  • rewrite themselves in place to point at the attached result returned by attach
  • return only the subset of attached child results that should become explicit non-structural cache dependency edges

Returned deps are treated as owned: the install span of the parent (the API span that returned the parent value to a session) is attributed to each dep, so failures in the dep's lazy work mark the parent's install span as caused-failed. Implementations that want some deps to be liveness-only (no failure attribution) should implement HasDependencyResultsKinds instead.

type HasDependencyResultsKinds added in v0.21.0 

type HasDependencyResultsKinds interface {
	AttachDependencyResultsKinds(context.Context, AnyResult, func(AnyResult) (AnyResult, error)) ([]DependencyResult, error)
}

HasDependencyResultsKinds is the kind-aware variant of HasDependencyResults. When a value implements both, this one is preferred — the result kind flag (Owned) controls install-span propagation for failure attribution.

type HasLazyEvaluation added in v0.21.0 

type HasLazyEvaluation interface {
	LazyEvalFunc() LazyEvalFunc
}

HasLazyEvaluation is implemented by values carrying deferred work that Cache.Evaluate forces. A successful callback run consumes the value's deferred work; implementations should return nil from LazyEvalFunc afterwards. Core types retain their Lazy operation and report completion through its state before cache-side bookkeeping finishes. The cache enforces the consumption independently: once a callback body has succeeded, later attempts retry only cache-side bookkeeping and never re-read the value's callback, so an implementation that keeps returning a non-nil function cannot cause the body to run twice.

type HasLazyEvaluationParts 

type HasLazyEvaluationParts interface {
	HasLazyEvaluation

	// ResolveLazyEvalGroups maps the requested parts to the groups that
	// fill them, in the order they should be evaluated. nil parts means
	// "every group that currently has deferred work". self is the
	// attached result wrapping this value. Resolution may evaluate the
	// value's own metadata part (via the cache) to settle positional
	// parts; it must never evaluate snapshot content. The mapping must be
	// deterministic and stable once metadata is settled.
	ResolveLazyEvalGroups(ctx context.Context, self AnyResult, parts []PartKey) ([]LazyGroupKey, error)

	// LazyEvalFuncForGroup returns the group's remaining deferred work,
	// nil when none remains. Same consumption contract as LazyEvalFunc,
	// per group: a successful body run consumes the group's work, and the
	// cache independently guarantees the body never runs twice.
	LazyEvalFuncForGroup(LazyGroupKey) LazyEvalFunc
}

HasLazyEvaluationParts is implemented by values whose deferred work is split into independently evaluable groups. Values that implement only HasLazyEvaluation have exactly one group, LazyGroupWhole.

type HasLazyEvaluationReporting 

type HasLazyEvaluationReporting interface {
	HasPendingLazyComputation() bool

	// LazyGroupStoredPart returns the saved part opened by this group, or the
	// empty key for ordinary computation. The answer remains stable after body
	// consumption and operation clearing, including bookkeeping-only retries.
	LazyGroupStoredPart(LazyGroupKey) PartKey
}

HasLazyEvaluationReporting distinguishes remaining computation from opening an already computed local part. Operational evaluation and child construction still use HasLazyEvaluation. These methods must not perform I/O or evaluation.

type HasPartHost 

type HasPartHost interface{ BindPartHost(*PartHost) }

HasPartHost binds a typed adapter to the stable owning row. Binding never creates a gate and decoding another representation keeps the same host.

type HasPartHostBinding 

type HasPartHostBinding interface{ PartHostBinding() *PartHost }

type HasResultReference 

type HasResultReference interface {
	InitializeResultReference(self AnyResult)
}

HasResultReference restores a value's internal reference to its own attached result. The cache calls this before publishing a decoded persisted payload. Implementations must preserve references that are already set, and must not resolve self: the payload is still being installed.

type HeldCapturedClosure 

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

HeldCapturedClosure protects every exact source row and offer while storage opens and provider consumption run outside graph and value locks.

func (*HeldCapturedClosure) Release 

func (capture *HeldCapturedClosure) Release(ctx context.Context) error

type HeldValueState 

type HeldValueState struct {
	Replacements  uint64
	Deps          []uint64
	Parts         []PersistedPartAddress
	OfferedParts  []PersistedPartAddress
	ExpiresAtUnix int64
	ContentDigest digest.Digest
}

HeldValueState is one observation of the value state of a holding's copy: the counterpart entry's replacement count, read under the lock that read the rest, and that value's dependencies, complete and offered parts, own expiry (0: none) and content digest. A field the observation doesn't carry is empty.

The count orders observations of value state, whatever order they arrive in (applyHeldValueStateLocked): an entry's parts go backward only when its value is replaced, and each replacement raises its count.

type HolderKey 

type HolderKey struct {
	Cache  CacheID
	Number uint64
}

HolderKey names one entry of one engine cache: the cache's identity and the entry's result number there.

type ID 

type ID[T Typed] struct {
	// contains filtered or unexported fields
}

ID is a type-checked ID scalar.

func NewID 

func NewID[T Typed](id *call.ID) ID[T]

func (*ID[T]) Decode 

func (i *ID[T]) Decode(str string) error

func (ID[T]) DecodeInput 

func (i ID[T]) DecodeInput(val any) (Input, error)

New creates a new ID with the given value.

It accepts either an *call.ID or a string. The string is expected to be the base64-encoded representation of an *call.ID.

func (ID[T]) Decoder 

func (i ID[T]) Decoder() InputDecoder

func (ID[T]) Display 

func (i ID[T]) Display() string

func (ID[T]) Encode 

func (i ID[T]) Encode() (string, error)

func (ID[T]) ExpectedTypeName added in v0.21.1 

func (i ID[T]) ExpectedTypeName() string

ExpectedTypeName returns the name of the expected type for this ID, e.g. "Container" for ID[*Container]. Used for @expectedType directives and runtime validation.

func (ID[T]) ID 

func (i ID[T]) ID() (*call.ID, error)

ID returns the ID of the value.

func (ID[T]) Load 

func (i ID[T]) Load(ctx context.Context, server *Server) (res ObjectResult[T], _ error)

Load loads the instance with the given ID from the server.

func (ID[T]) MarshalJSON 

func (i ID[T]) MarshalJSON() ([]byte, error)

func (ID[T]) SetField 

func (i ID[T]) SetField(v reflect.Value) error

func (ID[T]) String 

func (i ID[T]) String() string

String returns the ID in TypeName@<encoded-id> debug format.

func (ID[T]) ToLiteral 

func (i ID[T]) ToLiteral() call.Literal

func (ID[T]) Type 

func (i ID[T]) Type() *ast.Type

Type returns the GraphQL type of the value — always `ID!`.

func (ID[T]) TypeDefinition 

func (i ID[T]) TypeDefinition(view call.View) *ast.Definition

TypeDefinition returns the definition for the ID scalar. Since all IDs share the same scalar type, this returns the built-in ID definition.

func (ID[T]) TypeName 

func (i ID[T]) TypeName() string

TypeName returns "ID" — all typed IDs share the same scalar in the schema. The expected type is conveyed via @expectedType directives on arguments.

func (*ID[T]) UnmarshalJSON 

func (i *ID[T]) UnmarshalJSON(p []byte) error

type IDType 

type IDType interface {
	Input
	IDable
	ScalarType
}

type IDable 

type IDable interface {
	// ID returns the runtime handle ID of the value.
	ID() (*call.ID, error)
}

type ImplementsChecker added in v0.21.1 

type ImplementsChecker func(typeName, ifaceName string) bool

ImplementsChecker is a function that checks whether a type (by name) implements a given interface (by name). This is used for covariant return type checking.

type ImplicitInput added in v0.21.0 

type ImplicitInput struct {
	Name     string
	Resolver ImplicitInputResolver
}

func PerCallWhen 

func PerCallWhen(argName string, input ImplicitInput) ImplicitInput

PerCallWhen wraps input so that a call passing argName: true gets a fresh per-call key, like PerCallInput. The input keeps its name, and its value when argName is false or absent, so ordinary calls keep their digests. Use it for an argument that asks a lookup to resolve live (e.g. noLock): the call itself must not be answered from an earlier one.

func PerSchemaInput added in v0.21.0 

func PerSchemaInput(srv *Server) ImplicitInput

PerSchemaInput scopes a call ID to the server schema digest.

func RequestedCacheInput added in v0.21.0 

func RequestedCacheInput(argName string) ImplicitInput

RequestedCacheInput scopes a call ID according to a boolean argument: false => PerClientInput, true => PerCallInput.

type ImplicitInputResolver added in v0.21.0 

type ImplicitInputResolver func(context.Context, map[string]Input) (Input, error)

type ImportedValue 

type ImportedValue struct {
	Ordinal  TransferOrdinal
	ResultID uint64
}

type Input 

type Input interface {
	// All Inputs are typed.
	Typed
	// All Inputs are able to be represented as a Literal.
	call.Literate
	// All Inputs now how to decode new instances of themselves.
	Decoder() InputDecoder
}

Input represents any value which may be passed as an input.

type InputDecoder 

type InputDecoder interface {
	// Decode converts a value to the Input type, if possible.
	DecodeInput(any) (Input, error)
}

InputDecoder is a type that knows how to decode values into Inputs.

type InputObject 

type InputObject[T Type] struct {
	Value T
	// contains filtered or unexported fields
}

func (InputObject[T]) Decoder 

func (InputObject[T]) Decoder() InputDecoder

func (InputObject[T]) ToLiteral 

func (input InputObject[T]) ToLiteral() call.Literal

func (InputObject[T]) Type 

func (InputObject[T]) Type() *ast.Type

type InputObjectSpec 

type InputObjectSpec struct {
	Name        string
	Description string
	Fields      InputSpecs
}

func MustInputSpec 

func MustInputSpec(val Type) InputObjectSpec

func (InputObjectSpec) Install 

func (spec InputObjectSpec) Install(srv *Server, filter ...ViewFilter)

func (InputObjectSpec) Type 

func (spec InputObjectSpec) Type() *ast.Type

func (InputObjectSpec) TypeDefinition 

func (spec InputObjectSpec) TypeDefinition(view call.View) *ast.Definition

func (InputObjectSpec) TypeName 

func (spec InputObjectSpec) TypeName() string

type InputSpec 

type InputSpec struct {
	// Name is the name of the argument.
	Name string
	// Description is the description of the argument.
	Description string
	// Type is the type of the argument.
	Type Input
	// Default is the default value of the argument.
	Default Input
	// DeprecatedReason deprecates the input and provides a reason.
	DeprecatedReason *string
	// ExperimentalReason marks the field as experimental and provides a reason.
	ExperimentalReason string
	// Sensitive indicates that the value of this arg is sensitive and should be
	// omitted from telemetry.
	Sensitive bool
	// Directives is the list of GraphQL directives attached to this input.
	Directives []*ast.Directive

	// ViewFilter is filter that specifies under which views this field is
	// accessible. If not view is present, the default is the "global" view.
	ViewFilter ViewFilter

	// Internal indicates that this input can only be set by internal server
	// calls, never by external clients. It may appear in IDs sent to/from
	// clients, but can't be set in new graphql queries.
	// This argument will not be exposed in the introspection schema.
	Internal bool

	// LazyRef marks an ID-typed argument whose value is not needed to
	// reconstruct the receiver's state when an ID is loaded from its recipe.
	// The recipe loader carries such an argument through as a lazy reference
	// instead of eagerly evaluating it (and everything it depends on). The
	// field's resolver is responsible for loading the referenced object
	// lazily, only if and when it actually needs the value.
	//
	// This exists so that persisted state referencing an object whose
	// construction has side effects (or has since become impossible to
	// reproduce) can still be restored: e.g. LLM.withTools records the bound
	// object only to expose its type's methods as tools, so restoring the
	// conversation must not re-run the call that produced that object.
	LazyRef bool
}

InputSpec specifies a field argument, or an input field.

type InputSpecs 

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

func InputSpecsForType added in v0.17.2 

func InputSpecsForType(obj any, optIn bool) (InputSpecs, error)

func NewInputSpecs added in v0.18.6 

func NewInputSpecs(specs ...InputSpec) InputSpecs

func (*InputSpecs) Add added in v0.18.6 

func (specs *InputSpecs) Add(target ...InputSpec)

func (InputSpecs) ArgumentDefinitions 

func (specs InputSpecs) ArgumentDefinitions(view call.View) []*ast.ArgumentDefinition

func (InputSpecs) Decode added in v0.17.2 

func (specs InputSpecs) Decode(inputs map[string]Input, dest any, view call.View) error

func (InputSpecs) FieldDefinitions 

func (specs InputSpecs) FieldDefinitions(view call.View) (defs []*ast.FieldDefinition)

func (InputSpecs) HasRequired added in v0.19.7 

func (specs InputSpecs) HasRequired(view call.View) bool

func (InputSpecs) Input added in v0.18.6 

func (specs InputSpecs) Input(name string, view call.View) (InputSpec, bool)

func (InputSpecs) Inputs added in v0.18.6 

func (specs InputSpecs) Inputs(view call.View) (args []InputSpec)

func (InputSpecs) InputsFromResultCallArgs added in v0.21.0 

func (specs InputSpecs) InputsFromResultCallArgs(ctx context.Context, args []*ResultCallArg, view call.View) (map[string]Input, error)

type Inputs 

type Inputs []NamedInput

func (Inputs) Lookup 

func (args Inputs) Lookup(name string) (Input, bool)

type InstallHook added in v0.17.0 

type InstallHook interface {
	InstallObject(ObjectType, ...*ast.Directive)
	InstallInterface(*Interface, ...*ast.Directive)
}

type InstallHookForker added in v0.21.0 

type InstallHookForker interface {
	ForkInstallHook(*Server) InstallHook
}

InstallHookForker is implemented by install hooks that carry server-specific state and must be rebound when a server is forked.

type InstalledOutputs 

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

InstalledOutputs is immutable after publication. Installation identity is distinct from the generation executing a later bookkeeping-only retry.

type Int 

type Int int64

Int is a GraphQL Int scalar.

func NewInt 

func NewInt[T constraints.Integer](val T) Int

func (Int) DecodeInput 

func (Int) DecodeInput(val any) (Input, error)

func (Int) Decoder 

func (Int) Decoder() InputDecoder

func (Int) Int 

func (i Int) Int() int

func (Int) Int64 

func (i Int) Int64() int64

func (Int) MarshalJSON 

func (i Int) MarshalJSON() ([]byte, error)

func (Int) SetField 

func (i Int) SetField(v reflect.Value) error

func (Int) ToLiteral 

func (i Int) ToLiteral() call.Literal

func (Int) Type 

func (Int) Type() *ast.Type

func (Int) TypeDefinition 

func (i Int) TypeDefinition(view call.View) *ast.Definition

func (Int) TypeName 

func (Int) TypeName() string

func (*Int) UnmarshalJSON 

func (i *Int) UnmarshalJSON(p []byte) error

type Interface added in v0.21.1 

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

Interface represents a GraphQL Interface type in dagql.

Unlike Class (which represents object types), an Interface only declares field *specs* — it has no resolvers of its own. Concrete objects that implement the interface provide the actual field implementations.

func NewInterface added in v0.21.1 

func NewInterface(name, description string) *Interface

NewInterface creates a new Interface with the given name and description.

func (*Interface) AddField added in v0.21.1 

func (iface *Interface) AddField(spec InterfaceFieldSpec)

AddField adds a field spec to the interface.

func (*Interface) Definition added in v0.21.1 

func (iface *Interface) Definition(view call.View) *ast.Definition

Definition returns the ast.Definition for this interface for the given view.

func (*Interface) FieldSpec added in v0.21.1 

func (iface *Interface) FieldSpec(name string, view call.View) (FieldSpec, bool)

FieldSpec looks up a field spec by name for the given view.

func (*Interface) FieldSpecs added in v0.21.1 

func (iface *Interface) FieldSpecs(view call.View) []FieldSpec

FieldSpecs returns the interface's field specs visible under the given view.

func (*Interface) HasImplementor added in v0.21.1 

func (iface *Interface) HasImplementor(typeName string) bool

HasImplementor returns true if the named object or interface type implements this interface.

func (*Interface) ImplementInterface added in v0.21.1 

func (iface *Interface) ImplementInterface(other *Interface)

ImplementInterface declares that this interface implements another interface. This is the interface-to-interface equivalent of Class.Implements.

func (*Interface) Implementors added in v0.21.1 

func (iface *Interface) Implementors() map[string]struct{}

Implementors returns a snapshot of the type names that implement this interface.

func (*Interface) Interfaces added in v0.21.1 

func (iface *Interface) Interfaces() map[string]*Interface

Interfaces returns a snapshot of the interfaces that this interface implements.

func (*Interface) ParseField added in v0.21.1 

func (iface *Interface) ParseField(ctx context.Context, view call.View, astField *ast.Field, vars map[string]any) (Selector, *ast.Type, error)

ParseField parses an AST field selection against this interface's field specs. This is used when a query selects fields on an interface-typed return value.

func (*Interface) SatisfiedByInterface added in v0.21.1 

func (iface *Interface) SatisfiedByInterface(other *Interface, view call.View, checkers ...ImplementsChecker) bool

SatisfiedByInterface returns true if the given interface structurally satisfies this interface — i.e. it has all fields required by this interface with compatible return types and arguments.

The optional implementsChecker allows covariant return type checking and contravariant argument type checking, same as Satisfies.

func (*Interface) Satisfies added in v0.21.1 

func (iface *Interface) Satisfies(obj ObjectType, view call.View, checkers ...ImplementsChecker) bool

Satisfies returns true if the given object type structurally satisfies this interface — i.e. it has all fields required by the interface with compatible return types and arguments.

The optional implementsChecker allows covariant return type checking: if the interface declares `foo: SomeIface` and the object has `foo: ConcreteObj`, the checker verifies that ConcreteObj implements SomeIface. The same checker is used in reverse for contravariant argument type checking.

func (*Interface) TypeDescription added in v0.21.1 

func (iface *Interface) TypeDescription() string

TypeDescription returns the description of the interface type.

func (*Interface) TypeName added in v0.21.1 

func (iface *Interface) TypeName() string

TypeName returns the name of the interface type.

func (*Interface) Typed added in v0.21.1 

func (iface *Interface) Typed() Typed

Typed returns a Typed marker for this interface, suitable for use as a field return type.

func (*Interface) View 

func (iface *Interface) View(view ViewFilter) *Interface

func (*Interface) ViewFilter 

func (iface *Interface) ViewFilter() ViewFilter

type InterfaceFieldSpec added in v0.21.1 

type InterfaceFieldSpec struct {
	FieldSpec
	MinVersion call.View // view gating, same as object fields
}

InterfaceFieldSpec pairs a FieldSpec with optional view gating, mirroring how object fields work.

type InterfaceImplementor added in v0.21.1 

type InterfaceImplementor interface {
	ImplementInterface(iface *Interface)
	// ImplementInterfaceUnchecked declares interface conformance without
	// performing dagql's structural Satisfies check. This is used when a
	// higher-level layer (e.g. core's IsSubtypeOf) has already validated
	// conformance with richer semantics (covariance, contravariance, etc.).
	ImplementInterfaceUnchecked(iface *Interface)
}

InterfaceImplementor is implemented by object types that can declare interface conformance. Class[T] satisfies this interface.

type LazyEvalFunc added in v0.21.0 

type LazyEvalFunc func(context.Context) error

type LazyEvaluationPhase 

type LazyEvaluationPhase uint8
const (
	LazyEvaluationOpen LazyEvaluationPhase = iota
	LazyEvaluationPreparing
	LazyEvaluationRunning
	LazyEvaluationEvaluated
)

type LazyGroupAddress 

type LazyGroupAddress struct {
	OutputPath PersistedRefPath
	Group      LazyGroupKey
}

type LazyGroupKey 

type LazyGroupKey string

LazyGroupKey identifies one evaluation group of a result. Every part maps to exactly one group; a group's single body fills all its parts. 

const LazyGroupWhole LazyGroupKey = "whole"

LazyGroupWhole is the implicit group of values that do not split their deferred work. It fills every part.

type LazyOperationInvocation 

type LazyOperationInvocation interface {
	Run(context.Context) error
	Capture(context.Context, *PersistEncodeContext) (PersistedObjectEncoding, error)
	Release(context.Context) error
}

type LazyOperationRoute 

type LazyOperationRoute struct {
	Group            LazyGroupAddress
	WriteSet         []PersistedPartAddress
	HasLazyOperation bool
	NeedsMetadata    bool
	Delegation       *PartDelegation
}

LazyOperationRoute is data-only. NeedsMetadata means a caller must finish metadata before asking for the concrete positional write set.

type LazyTaskSpec 

type LazyTaskSpec struct {
	Body           func(context.Context) error
	AfterOwnerSync func(context.Context) error
	Settled        func(context.Context) error
	OwnerSyncReady <-chan struct{}
	NoJoin         bool
}

LazyTaskSpec supplies a coordination body, independent of the value's native lazy callback. A successful publication retains the continuation on failure.

type LoadByIDFunc added in v0.21.0 

type LoadByIDFunc func(context.Context, AnyResult, map[string]Input) (AnyResult, error)

LoadByIDFunc is the builtin execution path for schema-generated load<Type>FromID fields.

type MergeReply 

type MergeReply struct {
	// Values has one entry per merged record, in dependency order.
	Values []MergedValue
	// Roots has one entry per root of the bundle.
	Roots []MergedRoot
	// Generation and EngineTimeUnixNano are the cache's start count and clock
	// at the commit. They order the reply's retention among the cache's other
	// observations.
	Generation         uint64
	EngineTimeUnixNano int64
	// Change is, on the Cloud, what the sender's holdings changed, for the
	// service's next CollectRemoteHoldings.
	Change RemoteChange
	// Committed reports that the merge changed the cache. A committed merge
	// can still return an error, from releasing a replaced value after the
	// lock; the reply then describes what the cache holds all the same.
	Committed bool
	// CommitHold is how long the commit held egraphMu, from taking it to
	// releasing it.
	CommitHold time.Duration
}

MergeReply is what a merge committed, read under the lock that committed it.

func (MergeReply) Imported 

func (r MergeReply) Imported() []ImportedValue

Imported returns the unexpired roots' numbers.

type MergedRoot 

type MergedRoot struct {
	Ordinal TransferOrdinal
	// Expired marks a root that had expired when the merge decided: it was
	// skipped, with whatever only it needed.
	Expired                bool
	Number                 uint64
	Retained               bool
	RetentionExpiresAtUnix int64
}

MergedRoot is one root of the bundle: its target and retention, or expired.

type MergedValue 

type MergedValue struct {
	Ordinal      TransferOrdinal
	Number       uint64
	Replacements uint64
	// ExpiresAtUnix is the target's own expiry (0: none).
	ExpiresAtUnix int64
	// Deps are the target's actual direct dependencies by number: a kept
	// value's own, which can differ from the record's.
	Deps []uint64
	// Parts are the target's complete parts, and OfferedParts those it has an
	// offer of and not the bytes.
	Parts        []PersistedPartAddress
	OfferedParts []PersistedPartAddress
}

MergedValue is one merged record's target as the commit left it.

type NamedInput 

type NamedInput struct {
	Name  string
	Value Input
}

func (NamedInput) String 

func (arg NamedInput) String() string

type NodeFuncHandler added in v0.16.3 

type NodeFuncHandler[T Typed, A any, R any] func(ctx context.Context, self ObjectResult[T], args A) (R, error)

type NotReplayableCall 

type NotReplayableCall struct {
	Field  string
	Digest digest.Digest
	Reason string
}

NotReplayableCall identifies a field that makes a recipe non-replayable.

type Nullable 

type Nullable[T Typed] struct {
	Value T
	Valid bool
}

Nullable wraps a type and allows it to be null.

This is used for optional arguments and return values.

func MapOpt 

func MapOpt[I Input, R Typed](opt Optional[I], fn func(I) (R, error)) (Nullable[R], error)

func NonNull 

func NonNull[T Typed](val T) Nullable[T]

func Null 

func Null[T Typed]() Nullable[T]

func (Nullable[T]) Deref 

func (n Nullable[T]) Deref() (Typed, bool)

func (Nullable[T]) DerefToResult added in v0.18.13 

func (n Nullable[T]) DerefToResult(
	call *ResultCall,
) (AnyResult, bool)

func (Nullable[T]) MarshalJSON 

func (n Nullable[T]) MarshalJSON() ([]byte, error)

func (Nullable[T]) Type 

func (n Nullable[T]) Type() *ast.Type

func (*Nullable[T]) UnmarshalJSON 

func (n *Nullable[T]) UnmarshalJSON(p []byte) error

type ObjectResult added in v0.18.13 

type ObjectResult[T Typed] struct {
	Result[T]
	// contains filtered or unexported fields
}

func LoadIDResults added in v0.18.13 

func LoadIDResults[T Typed](ctx context.Context, srv *Server, ids []ID[T]) ([]ObjectResult[T], error)

func NewObjectResultForCall added in v0.21.0 

func NewObjectResultForCall[T Typed](
	self T,
	srv *Server,
	call *ResultCall,
) (res ObjectResult[T], _ error)

func NewObjectResultForCurrentCall added in v0.21.0 

func NewObjectResultForCurrentCall[T Typed](
	ctx context.Context,
	srv *Server,
	self T,
) (ObjectResult[T], error)

func (ObjectResult[T]) DerefValue added in v0.18.13 

func (r ObjectResult[T]) DerefValue() (AnyResult, bool)

func (ObjectResult[T]) MarshalJSON added in v0.18.13 

func (r ObjectResult[T]) MarshalJSON() ([]byte, error)

func (ObjectResult[T]) NullableWrapped added in v0.21.0 

func (r ObjectResult[T]) NullableWrapped() AnyResult

func (ObjectResult[T]) ObjectType added in v0.18.13 

func (r ObjectResult[T]) ObjectType() ObjectType

ObjectType returns the ObjectType of the instance.

func (ObjectResult[T]) Receiver added in v0.21.0 

func (r ObjectResult[T]) Receiver(ctx context.Context, srv *Server) (AnyObjectResult, error)

func (ObjectResult[T]) Select added in v0.18.13 

func (r ObjectResult[T]) Select(ctx context.Context, s *Server, sel Selector) (AnyResult, error)

Select calls the field on the instance specified by the selector

func (ObjectResult[T]) SetField added in v0.18.13 

func (r ObjectResult[T]) SetField(field reflect.Value) error

func (ObjectResult[T]) WithContentDigest added in v0.19.11 

func (r ObjectResult[T]) WithContentDigest(ctx context.Context, contentDigest digest.Digest, additionalLabels ...string) (ObjectResult[T], error)

func (ObjectResult[T]) WithContentDigestAny added in v0.20.0 

func (r ObjectResult[T]) WithContentDigestAny(ctx context.Context, customDigest digest.Digest, additionalLabels ...string) (AnyResult, error)

WithContentDigestAny is WithContentDigest but returns an AnyResult, required for polymorphic code paths like module function call plumbing.

func (ObjectResult[T]) WithSessionResourceHandle added in v0.21.0 

func (r ObjectResult[T]) WithSessionResourceHandle(ctx context.Context, handle SessionResourceHandle) (ObjectResult[T], error)

func (ObjectResult[T]) WithSessionResourceHandleAny added in v0.21.0 

func (r ObjectResult[T]) WithSessionResourceHandleAny(ctx context.Context, handle SessionResourceHandle) (AnyResult, error)

type ObjectResultArray added in v0.18.13 

type ObjectResultArray[T Typed] []ObjectResult[T]

func (ObjectResultArray[T]) AttachDependencyResults added in v0.21.0 

func (arr ObjectResultArray[T]) AttachDependencyResults(
	_ context.Context,
	_ AnyResult,
	attach func(AnyResult) (AnyResult, error),
) ([]AnyResult, error)

func (ObjectResultArray[T]) Element added in v0.18.13 

func (arr ObjectResultArray[T]) Element() Typed

func (ObjectResultArray[T]) Len added in v0.18.13 

func (arr ObjectResultArray[T]) Len() int

func (ObjectResultArray[T]) Nth added in v0.18.13 

func (arr ObjectResultArray[T]) Nth(i int) (Typed, error)

func (ObjectResultArray[T]) NthValue added in v0.18.13 

func (arr ObjectResultArray[T]) NthValue(i int, _ *ResultCall) (AnyResult, error)

func (ObjectResultArray[T]) Type added in v0.18.13 

func (i ObjectResultArray[T]) Type() *ast.Type

type ObjectType 

type ObjectType interface {
	Type
	// Typed returns a Typed value whose Type refers to the object type.
	Typed() Typed
	// IDType returns the scalar type for the object's IDs.
	IDType() (IDType, bool)
	// New creates a new instance of the type.
	New(val AnyResult) (AnyObjectResult, error)
	// ParseField parses the given field and returns a Selector and an expected
	// return type.
	ParseField(ctx context.Context, view call.View, astField *ast.Field, vars map[string]any) (Selector, *ast.Type, error)
	// Extend registers an additional field onto the type.
	//
	// Unlike natively added fields, the extended func is limited to the external
	// Object interface.
	// cacheConfigFunc is optional, if not set the default dagql ID cache key will be used.
	Extend(spec FieldSpec, fun FieldFunc)
	// FieldSpec looks up a field spec by name.
	FieldSpec(name string, view call.View) (FieldSpec, bool)
	// FieldSpecs returns all field specs visible under the given view.
	FieldSpecs(view call.View) []FieldSpec
}

ObjectType represents a GraphQL Object type.

type OfferDisposition 

type OfferDisposition struct {
	Address  PersistedPartAddress
	Outcome  OfferOutcome
	Replaced bool
	OfferRev uint64
	Err      error
	// Replacements and Deps are the receiver's replacement count and direct
	// dependencies, read under the lock that decided Outcome: the value state
	// the outcome describes.
	Replacements uint64
	Deps         []uint64
}

type OfferOutcome 

type OfferOutcome uint8
const (
	OfferUnavailable OfferOutcome = iota
	OfferAccepted
	OfferAlreadyComplete
	OfferExecutionStarted
	OfferInvalid
)

type OfferedChain 

type OfferedChain struct {
	Layers     []snapshots.ExportLayer       `json:"layers"`
	Addresses  map[digest.Digest]BlobAddress `json:"addresses,omitempty"`
	RenewalKey string                        `json:"renewalKey,omitempty"`
}

type OnReleaseFunc added in v0.20.0 

type OnReleaseFunc = func(context.Context) error

type OnReleaser added in v0.16.3 

type OnReleaser interface {
	OnRelease(context.Context) error
}

A type that has a callback attached that needs to always run when the result is removed from the cache

type OperationLeaseProvider added in v0.21.0 

type OperationLeaseProvider interface {
	WithOperationLease(context.Context) (context.Context, func(context.Context) error, error)
}

type OperationLeaseProviderFunc added in v0.21.0 

type OperationLeaseProviderFunc func(context.Context) (context.Context, func(context.Context) error, error)

func (OperationLeaseProviderFunc) WithOperationLease added in v0.21.0 

func (f OperationLeaseProviderFunc) WithOperationLease(ctx context.Context) (context.Context, func(context.Context) error, error)

type Optional 

type Optional[I Input] struct {
	Value I
	// true if the value is set
	Valid bool
}

Optional wraps a type and allows it to be null.

This is used for optional arguments and return values.

func NoOpt 

func NoOpt[I Input]() Optional[I]

NoOpt returns an empty Optional value.

func Opt 

func Opt[I Input](v I) Optional[I]

func (Optional[I]) AsPtr added in v0.18.18 

func (n Optional[I]) AsPtr() *I

func (Optional[I]) DecodeInput 

func (o Optional[I]) DecodeInput(val any) (Input, error)

func (Optional[I]) Decoder 

func (o Optional[I]) Decoder() InputDecoder

func (Optional[I]) Deref 

func (o Optional[I]) Deref() (Typed, bool)

func (Optional[I]) GetOr 

func (n Optional[I]) GetOr(v I) I

GetOr returns the value of the Optional, or the given value if the Optional is empty.

func (Optional[I]) MarshalJSON 

func (o Optional[I]) MarshalJSON() ([]byte, error)

func (Optional[I]) SetField added in v0.18.18 

func (o Optional[I]) SetField(val reflect.Value) error

func (Optional[I]) ToLiteral 

func (o Optional[I]) ToLiteral() call.Literal

func (Optional[I]) ToNullable 

func (o Optional[I]) ToNullable() Nullable[I]

func (Optional[I]) Type 

func (o Optional[I]) Type() *ast.Type

func (*Optional[I]) UnmarshalJSON 

func (o *Optional[I]) UnmarshalJSON(p []byte) error

type OriginalPermit 

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

type OutputRevision 

type OutputRevision uint64

OutputRevision identifies one typed output publication within this process. It is never part of a persisted or transferred identity.

type PanicError added in v0.10.0 

type PanicError struct {
	Cause     any
	Self      AnyResult
	Selection Selection
	Stack     []byte
}

func (PanicError) Error added in v0.10.0 

func (err PanicError) Error() string

type PartAvailability 

type PartAvailability struct {
	State PartAvailabilityState
	Donor uint64
	Part  PersistedPartOffer
}

PartAvailability is AvailablePart's answer. Donor is the number of the entry whose stored part or record it is, and Part the stored part, for PartStored.

type PartAvailabilityState 

type PartAvailabilityState uint8

PartAvailabilityState is what a blob-backed cache has of an entry's part. 

const (
	// PartUnavailable: the cache has neither the part's bytes nor a record
	// that shows the part carries none.
	PartUnavailable PartAvailabilityState = iota
	// PartStored: the part's layer chain is in the cache's blob store.
	PartStored
	// PartAbsent: a stored record maps the part as absent, a part with no
	// bytes, so it is never stored.
	PartAbsent
)

type PartBatchStorePreparer 

type PartBatchStorePreparer interface {
	PreparePartStores(context.Context, *PersistDecodeContext, PersistedRecord, []PartDescriptor, []snapshots.ImmutableRef) (PreparedPartStore, error)
}

A operation publishes its complete missing write set in one transaction.

type PartContentOverride 

type PartContentOverride interface {
	// Available is a pure address check; it must not request content.
	Available(PersistedPartOffer, time.Time) bool
	Provider(context.Context, PersistedPartOffer, *PartDemandState) content.InfoReaderProvider
}

PartContentOverride replaces a source's availability and provider. Only tests and the environment-gated transfer fixture set it; every other engine leaves it nil.

type PartContentSource 

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

PartContentSource is the cache's one content source. Ranking and chain installation both use it. A nil source behaves like one constructed with a nil transport: the default transport, no bridge and no override.

func NewPartContentSource 

func NewPartContentSource(transport http.RoundTripper) *PartContentSource

NewPartContentSource performs no I/O. In-package fixtures supply their controlled transport here.

func (*PartContentSource) Available 

func (s *PartContentSource) Available(offer PersistedPartOffer, now time.Time) bool

Available reports whether an offer can supply bytes now. An empty chain is scratch; otherwise every blob needs a usable address, or the offer needs a renewal key with a bridge attached. It performs no I/O.

func (*PartContentSource) Provider 

func (s *PartContentSource) Provider(ctx context.Context, offer PersistedPartOffer, demand *PartDemandState) content.InfoReaderProvider

Provider freezes the copied offer's layers and copies its addresses. It creates no request.

type PartCounters 

type PartCounters struct {
	Payload, Gate, Offers, Resources, Ownership uint64
}

PartCounters are the monotonic counters of one row that a changed site may compare. A site leaves the ones it does not compare zero.

type PartDelegation 

type PartDelegation struct {
	ParentResultID uint64
	Address        PersistedPartAddress
}

PartDelegation authorizes one unchanged part from the exact recorded parent. It is runtime routing data, never a saved operation or an equivalence claim.

type PartDemandState 

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

PartDemandState is one demand's runtime state. Its two sets have distinct keys: exhaustion by source, full address, content and admitted offer revision; renewal episodes by the demand's target address and blob digests.

type PartDescriptor 

type PartDescriptor struct {
	Family        string
	Address       PersistedPartAddress
	Value         *SnapshotValue
	Absent        bool
	SnapshotID    string
	DependencyIDs []uint64
}

type PartGateCell 

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

PartGateCell is a stable row attachment. Merely binding it allocates no gate.

type PartHost 

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

func (*PartHost) Admitted 

func (host *PartHost) Admitted(ctx context.Context) bool

func (*PartHost) DecodeContext 

func (host *PartHost) DecodeContext(ctx context.Context) *PersistDecodeContext

DecodeContext borrows this held owner's exact recorded identity and the context's dagql server.

func (*PartHost) Evaluate 

func (host *PartHost) Evaluate(ctx context.Context, parts ...PartKey) error

func (*PartHost) Managed 

func (host *PartHost) Managed() bool

func (*PartHost) RunNative 

func (host *PartHost) RunNative(ctx context.Context, group LazyGroupKey, parts []PartKey, body func(context.Context) error) error

RunNative enters the gate before the body takes any core latch. The raw callback remains the only owner of native completion and consumption.

func (*PartHost) SetContentDigestAfterEvaluation 

func (host *PartHost) SetContentDigestAfterEvaluation(ctx context.Context, contentDigest digest.Digest, labels ...string) error

SetContentDigestAfterEvaluation defers output equivalence until this native attempt has materialized and settled its output. Inline values do not have an independent result identity, so they cannot publish a digest on their owner.

type PartInstallOutcome 

type PartInstallOutcome uint8
const (
	PartInstallRefused PartInstallOutcome = iota
	PartInstallAlreadyInstalled
	PartInstalled
)

type PartKey 

type PartKey string

PartKey identifies one separately evaluable piece of a result's value. Keys are defined by the value's package; dagql treats them as opaque.

type PartNoProgressError 

type PartNoProgressError struct {
	Loop, Site                string
	ResultID                  uint64
	Address                   PersistedPartAddress
	Expected, Current         PartCounters
	FirstLoop                 string
	FirstIteration, Iteration uint64
}

PartNoProgressError reports the repeat. Expected and Current are the counters of row ResultID that the site compared at the repeated refusal.

func (*PartNoProgressError) Error 

func (e *PartNoProgressError) Error() string

func (*PartNoProgressError) Unwrap 

func (e *PartNoProgressError) Unwrap() error

type PartOutputOpener 

type PartOutputOpener interface {
	OpenPart(context.Context, PersistedPartAddress) error
}

PartOutputOpener opens a final local descriptor without evaluating an operation or changing the output's meaning. The cache has already joined its owner.

type PartOutputPhase 

type PartOutputPhase uint8
const (
	PartPending PartOutputPhase = iota
	PartOutputInstalled
	PartComplete
)

type PartPermit 

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

func (*PartPermit) Release 

func (permit *PartPermit) Release()

type PartPreparationContext 

type PartPreparationContext func(context.Context) (context.Context, *Server, error)

PartPreparationContext builds the engine-root context and schema-only server a typed sharing preparation decodes persisted values with. The cache never constructs one itself: a cache with no registered callback treats a typed receiver that needs service construction as ineligible, and leaves service-free and encoded installs available, decoding with no server.

type PartProbe 

type PartProbe struct {
	Descriptor                                         PartDescriptor
	LocalComplete, RestoreOnly, HasLazyOperation, Busy bool
	DescriptorRev                                      uint64
	OutputRev                                          OutputRevision
	OfferRev                                           uint64
	// contains filtered or unexported fields
}

type PartReadiness 

type PartReadiness uint8
const (
	PartRunnable PartReadiness = iota
	PartDownloadable
	PartReady
)

type PartSourceLease 

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

func (*PartSourceLease) Descriptor 

func (s *PartSourceLease) Descriptor() PartDescriptor

func (*PartSourceLease) Readiness 

func (s *PartSourceLease) Readiness() PartReadiness

func (*PartSourceLease) Release 

func (s *PartSourceLease) Release(ctx context.Context) error

type PartSourceScan 

type PartSourceScan struct {
	Source   *PartSourceLease
	NoSource *SourceCheck
}

type PartStorePreparer 

type PartStorePreparer interface {
	PreparePartStore(context.Context, *PersistDecodeContext, PersistedRecord, PartDescriptor, snapshots.ImmutableRef) (PreparedPartStore, error)
}

type PartTaskToken 

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

func PartTaskFromContext 

func PartTaskFromContext(ctx context.Context) *PartTaskToken

func (*PartTaskToken) SetContentDigestAfterEvaluation 

func (t *PartTaskToken) SetContentDigestAfterEvaluation(contentDigest digest.Digest, labels ...string) error

SetContentDigestAfterEvaluation schedules content equivalence for a successful output installation. Failed bodies and unfinished cleanup never publish it.

type PartWriterGate 

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

type PersistDecodeContext 

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

func NewPersistDecodeContext 

func NewPersistDecodeContext(dag *Server, resultID uint64, call *ResultCall) *PersistDecodeContext

NewPersistDecodeContext returns a decode context for one owner row. dag is the defining server; it may be nil only when the payload declares no references and needs no schema.

func (*PersistDecodeContext) Call 

func (dec *PersistDecodeContext) Call() *ResultCall

Call is the recorded call of the row being decoded.

func (*PersistDecodeContext) CallID 

func (dec *PersistDecodeContext) CallID(raw string) (*call.ID, error)

CallID restores a typed call ID from its tagged form. The empty string is explicit absence.

func (*PersistDecodeContext) Imported 

func (dec *PersistDecodeContext) Imported() bool

Imported reports the copied owner origin, never a temporary decoded row.

func (*PersistDecodeContext) PartHost 

func (dec *PersistDecodeContext) PartHost() *PartHost

func (*PersistDecodeContext) ResultID 

func (dec *PersistDecodeContext) ResultID() uint64

ResultID is the row being decoded, or zero for an inline value.

func (*PersistDecodeContext) ResultRef 

func (dec *PersistDecodeContext) ResultRef(ctx context.Context, resultID uint64) (AnyResult, error)

ResultRef loads the exact local row named by resultID. Zero is explicit absence and returns a nil result. The load never substitutes a session-selected equivalent; the outer client load still enforces transitive resource requirements before serving the owner.

The context borrows the lifetime of the decode that created it: that decode already runs inside an admitted cache operation (the owner's load or import), so child loads use the internal loader and never begin a new operation. A close that started after the owner was admitted therefore waits for the child load instead of failing it with ErrCacheClosed, exactly as the previous internal object loader behaved; external loads that begin after close remain rejected.

func (*PersistDecodeContext) Server 

func (dec *PersistDecodeContext) Server() *Server

Server is the defining server for the row being decoded.

func (*PersistDecodeContext) SnapshotRole 

func (dec *PersistDecodeContext) SnapshotRole(ctx context.Context, role string) (PersistedSnapshotRefLink, error)

SnapshotRole resolves one declared storage role of the owner row. It only returns the recorded identity; storage is never opened here.

func (*PersistDecodeContext) SnapshotRoles 

func (dec *PersistDecodeContext) SnapshotRoles(ctx context.Context) ([]PersistedSnapshotRefLink, error)

func (*PersistDecodeContext) SnapshotScope 

func (dec *PersistDecodeContext) SnapshotScope() PersistedSnapshotScope

SnapshotRoles returns the declared storage roles recorded for the owner row.

func (*PersistDecodeContext) WithSnapshotRoles 

func (dec *PersistDecodeContext) WithSnapshotRoles(links []PersistedSnapshotRefLink) *PersistDecodeContext

WithSnapshotRoles supplies an authoritative copied desired map, including empty.

type PersistEncodeContext 

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

PersistEncodeContext is the explicit context handed to every persisted object, list and lazy codec while a row is being encoded. It names the row being encoded (its ID and recorded call) and supplies the only two reference operations a codec may use: ResultRef, which turns an attached result into its exact local row ID, and CallID, which preserves a typed call ID in its original handle or recipe form. Neither operation establishes value equality; both only describe references the row already owns.

func NewPersistEncodeContext 

func NewPersistEncodeContext(cache PersistedObjectCache, resultID uint64, call *ResultCall) *PersistEncodeContext

NewPersistEncodeContext returns an encode context for one owner row. cache may be nil for detached encoding, in which case every ResultRef fails: a detached codec cannot describe row references.

func (*PersistEncodeContext) Cache 

func (enc *PersistEncodeContext) Cache() PersistedObjectCache

Cache exposes the row-identity lookup used by this context.

func (*PersistEncodeContext) Call 

func (enc *PersistEncodeContext) Call() *ResultCall

Call is the recorded call of the row being encoded, if known.

func (*PersistEncodeContext) CallID 

func (enc *PersistEncodeContext) CallID(id *call.ID) (string, error)

CallID preserves a typed call ID in its tagged form. Handle-form IDs keep their local row identity and exact recursive type; recipe-form IDs keep their call description. Nothing is executed or loaded.

func (*PersistEncodeContext) Quiescent 

func (enc *PersistEncodeContext) Quiescent() bool

Quiescent reports whether the shutdown persister is encoding after cache operations drained. Codecs may wait for transient read-only latch holders in this case. Live capture and detached encoding must not wait for bodies.

func (*PersistEncodeContext) ResultID 

func (enc *PersistEncodeContext) ResultID() uint64

ResultID is the row being encoded, or zero for a detached (inline) value.

func (*PersistEncodeContext) ResultRef 

func (enc *PersistEncodeContext) ResultRef(res AnyResult) (uint64, error)

ResultRef returns the attached local row ID of res. A result that is not cache-backed cannot be referenced and is an error: codecs record references only to rows that attachment already owns.

func (*PersistEncodeContext) SnapshotRole 

func (enc *PersistEncodeContext) SnapshotRole(role, refKey string) (PersistedSnapshotRefLink, error)

SnapshotRole records a declared storage role for the owner row. It only validates the declaration; storage is never opened.

type PersistedLazyOperationFactory 

type PersistedLazyOperationFactory interface {
	PrepareLazyOperation(context.Context, *PersistDecodeContext, PersistedRecord, LazyOperationRoute) (LazyOperationInvocation, error)
}

type PersistedNoReferences 

type PersistedNoReferences struct{}

PersistedNoReferences is the visitor for a family whose payload declares no references and no storage roles.

func (PersistedNoReferences) VisitPersistedReferences 

func (PersistedNoReferences) VisitPersistedReferences(v PersistedPayloadVisit, _ PersistedRefVisitor) (json.RawMessage, error)

type PersistedObject added in v0.21.0 

type PersistedObject interface {
	Typed
	EncodePersistedObject(context.Context, *PersistEncodeContext) (PersistedObjectEncoding, error)
}

PersistedObject is implemented by object self payloads that can be encoded directly for import-time cache persistence. Every implementing Go type must also be registered as a PersistedObjectFamily so its declared references can be visited without constructing the value.

type PersistedObjectCache added in v0.21.0 

type PersistedObjectCache interface {
	PersistedResultID(AnyResult) (uint64, error)
}

type PersistedObjectDecoder added in v0.21.0 

type PersistedObjectDecoder interface {
	Typed
	DecodePersistedObject(context.Context, *PersistDecodeContext, json.RawMessage) (Typed, error)
}

PersistedObjectDecoder is implemented by zero-value object types that know how to reconstruct a persisted object self payload without re-evaluating the original dagql call chain.

type PersistedObjectEncoding added in v0.21.0 

type PersistedObjectEncoding struct {
	JSON          json.RawMessage
	SnapshotLinks []PersistedSnapshotRefLink
}

type PersistedObjectFamily 

type PersistedObjectFamily struct {
	// Name is the stable family identifier written into envelopes.
	Name string
	// Typed is a zero value of the Go type whose codec produces this family.
	Typed Typed
	// Visitor walks the family's declared references.
	Visitor  PersistedPayloadVisitor
	Transfer PersistedTransferCodec
	// BackgroundDecode marks a family whose decoder has been audited for a
	// background, sessionless decode attempt: it loads only exact persisted
	// references and performs no client lookup, service start, schema
	// evaluation or output evaluation. It is false by default, so a newly
	// registered or unaudited decoder makes a receiver that needs it
	// ineligible for early sharing instead of entering a shared attempt.
	BackgroundDecode bool
}

PersistedObjectFamily identifies one Go payload family: the codec that produced an object envelope's bytes. TypeName identifies the GraphQL value; the family identifies how its bytes are read.

func PersistedObjectFamilies 

func PersistedObjectFamilies() []PersistedObjectFamily

PersistedObjectFamilies lists every registered family, sorted by name.

func PersistedObjectFamilyByName 

func PersistedObjectFamilyByName(name string) (PersistedObjectFamily, bool)

PersistedObjectFamilyByName returns the registered family with that name.

func PersistedObjectFamilyFor 

func PersistedObjectFamilyFor(self Typed) (PersistedObjectFamily, bool)

PersistedObjectFamilyFor returns the family registered for the Go type of self.

type PersistedOfferOwner 

type PersistedOfferOwner struct {
	DependencyIDs []uint64 `json:"dependencyIDs,omitempty"`
}

type PersistedOutputVersion 

type PersistedOutputVersion interface {
	PersistedOutputRevision() (OutputRevision, error)
}

PersistedOutputVersion reads under a nonblocking core persistence guard. Busy bodies and publications return ErrPersistStateNotReady.

type PersistedPartAddress 

type PersistedPartAddress struct {
	OutputPath PersistedRefPath `json:"outputPath,omitempty"`
	Part       PartKey          `json:"part"`
}

type PersistedPartDescriber 

type PersistedPartDescriber interface {
	DescribeParts(PersistedPayloadVisit) ([]PartProbe, error)
}

PersistedPartDescriber is pure: it neither loads references nor opens storage.

type PersistedPartInstaller 

type PersistedPartInstaller interface {
	PreparePartRecord(receiver PersistedRecord, source PersistedRecord, descriptor PartDescriptor, target PersistedPartAddress) (PersistedRecord, error)
}

PersistedPartInstaller prepares a complete root representation, including receiver-relative roles. Inline storage is attached at prepareInlineReadyPart.

type PersistedPartOffer 

type PersistedPartOffer struct {
	Address PersistedPartAddress `json:"address"`
	Value   SnapshotValue        `json:"value"`
	Chain   OfferedChain         `json:"chain"`
	Owner   PersistedOfferOwner  `json:"owner"`
}

func PlacePart 

func PlacePart(part PersistedPartOffer, place func(service uint64) (uint64, bool)) (PersistedPartOffer, bool)

PlacePart applies the placement rule with place, which maps a service entry's number to the receiver's entry for it. It returns the part with its services relocated and an owner of exactly those services, or false when a service can't be mapped: the part is not placed.

type PersistedPartRouter 

type PersistedPartRouter interface {
	RouteParts(PersistedPayloadVisit, PartKey) (LazyOperationRoute, error)
}

type PersistedPayloadVisit 

type PersistedPayloadVisit struct {
	Version       int
	Call          *ResultCall
	Path          PersistedRefPath
	Payload       json.RawMessage
	SnapshotLinks []PersistedSnapshotRefLink
}

PersistedPayloadVisit is the input to a codec family's reference visitor: the envelope version, the owner's recorded call, the declared position of the payload, its bytes and the owner's storage links. SnapshotLinks may be rewritten in place through VisitPersistedSnapshotRoles.

type PersistedPayloadVisitor 

type PersistedPayloadVisitor interface {
	VisitPersistedReferences(v PersistedPayloadVisit, visit PersistedRefVisitor) (json.RawMessage, error)
}

PersistedPayloadVisitor walks the declared references of one codec family's payload without constructing the typed value. It returns the payload, rewritten only when a reference was replaced. It performs no provider, schema, filesystem or execution work.

type PersistedRecord 

type PersistedRecord struct {
	ResultID      uint64                     `json:"resultID"`
	Envelope      PersistedResultEnvelope    `json:"envelope"`
	Call          *ResultCall                `json:"call"`
	SnapshotLinks []PersistedSnapshotRefLink `json:"snapshotLinks,omitempty"`
}

PersistedRecord is one persisted row as the reference visitor sees it: its identity, generic envelope, recorded call and declared storage links.

func VisitEncodedReferences 

func VisitEncodedReferences(rec PersistedRecord, visit PersistedRefVisitor) (PersistedRecord, error)

VisitEncodedReferences walks every declared reference of one persisted row: its own identity, list item rows, object payload references through the registered family visitor, recorded call references, and storage roles. The visitor may replace row identities and storage keys; the returned record carries the rewritten forms and the input is left untouched. Shared call subgraphs stay shared. No schema, provider, storage or typed construction is involved.

type PersistedRef 

type PersistedRef struct {
	// RecipeID is present only for a declared recipe-form call ID. Its
	// numeric ResultID is zero; a visitor may replace the immutable DAG.
	RecipeID *call.ID
	Kind     PersistedRefKind
	Path     PersistedRefPath
	ResultID uint64
	Role     string
	RefKey   string
}

PersistedRef is one declared reference reported by VisitEncodedReferences. Row references carry ResultID; storage roles carry Role and RefKey. A visitor may replace ResultID or RefKey to relocate the reference; every other field is descriptive.

type PersistedRefKind 

type PersistedRefKind string

PersistedRefKind classifies a declared reference position. 

const (
	// PersistedRefSelf is the envelope's own row identity. It is not an
	// ownership edge.
	PersistedRefSelf PersistedRefKind = "self"
	// PersistedRefChild is a required child row the owner depends on.
	PersistedRefChild PersistedRefKind = "child"
	// PersistedRefCall is a descriptive result reference inside a recorded
	// call frame. Nonzero refs keep their existing dependency ownership;
	// digest-only call descriptions add no row.
	PersistedRefCall PersistedRefKind = "call"
	// PersistedRefOutputRole is an immutable output storage role of the owner
	// row, described by a transferable snapshot identity.
	PersistedRefOutputRole PersistedRefKind = "output_role"
	// PersistedRefLocalBacking is a local mutable backing role of the owner
	// row. Its identity is engine-local configuration, never transferred.
	PersistedRefLocalBacking PersistedRefKind = "local_backing"
)

type PersistedRefPath 

type PersistedRefPath []PersistedRefPathElem

PersistedRefPath is the declared position of a reference relative to its exact owner row, interpreted by codec family and envelope version.

func (PersistedRefPath) Field 

func (p PersistedRefPath) Field(name string) PersistedRefPath

Field appends a declared field position.

func (PersistedRefPath) Index 

func (p PersistedRefPath) Index(i int) PersistedRefPath

Index appends a declared list position.

func (PersistedRefPath) String 

func (p PersistedRefPath) String() string

type PersistedRefPathElem 

type PersistedRefPathElem struct {
	Field   string `json:"field,omitempty"`
	Index   int    `json:"index,omitempty"`
	IsIndex bool   `json:"isIndex,omitempty"`
}

PersistedRefPathElem is one declared position: a field name or a list index relative to the enclosing owner.

type PersistedRefVisitor 

type PersistedRefVisitor func(ref *PersistedRef) error

PersistedRefVisitor observes or rewrites one declared reference.

type PersistedResultEncoding added in v0.21.0 

type PersistedResultEncoding struct {
	Envelope      PersistedResultEnvelope
	SnapshotLinks []PersistedSnapshotRefLink
}

type PersistedResultEnvelope added in v0.21.0 

type PersistedResultEnvelope struct {
	Imported      bool                 `json:"imported,omitempty"`
	PendingOffers []PersistedPartOffer `json:"pendingOffers,omitempty"`
	// StoredParts are a blob-backed cache's stored parts of the value, which
	// only its saved envelope carries: in memory they stay on the entry, so
	// no record sent to an engine carries them.
	StoredParts []PersistedPartOffer `json:"storedParts,omitempty"`
	Version     int                  `json:"version"`
	Kind        string               `json:"kind"`
	// TypeName identifies the GraphQL value type of object and scalar
	// envelopes.
	TypeName string `json:"typeName,omitempty"`
	// ObjectCodec identifies the Go payload family that produced ObjectJSON.
	// Every user-named module object shares one family; TypeName still names
	// the concrete GraphQL type.
	ObjectCodec string `json:"objectCodec,omitempty"`
	// ResultID is the attached row identity of the value. The root envelope
	// of a row repeats that row's ID; a null root keeps the identity of an
	// attached absent value; a result_ref item names another attached row.
	ResultID              uint64                    `json:"resultID,omitempty"`
	SessionResourceHandle SessionResourceHandle     `json:"sessionResourceHandle,omitempty"`
	ObjectJSON            json.RawMessage           `json:"objectJSON,omitempty"`
	ScalarJSON            json.RawMessage           `json:"scalarJSON,omitempty"`
	Items                 []PersistedResultEnvelope `json:"items,omitempty"`
}

PersistedResultEnvelope is the shared on-disk payload envelope for persisted result self values.

This is intentionally opaque at the DB level (stored as self_payload bytes), while still carrying enough structured data to decode common SDK-return shapes (scalars, object IDs, lists, nested combinations).

type PersistedSelfCodec added in v0.21.0 

type PersistedSelfCodec interface {
	EncodeResult(context.Context, PersistedObjectCache, AnyResult) (PersistedResultEncoding, error)
	DecodeResult(context.Context, *Server, uint64, *ResultCall, PersistedResultEnvelope) (AnyResult, error)
}

PersistedSelfCodec is the shared interface used to encode/decode result self payloads for disk persistence. 

var DefaultPersistedSelfCodec PersistedSelfCodec = defaultPersistedSelfCodec{}
type PersistedSnapshotRefLink struct {
	RefKey     string
	Role       string
	OutputPath PersistedRefPath `json:"outputPath,omitempty"`
}

PersistedSnapshotRefLink is a generic non-opaque link from a persisted result self payload to one durable snapshot ref key. 

func ClonePersistedSnapshotLinks(links []PersistedSnapshotRefLink) []PersistedSnapshotRefLink

ClonePersistedSnapshotLinks gives codec adapters the same independent copy used by cache capture, decode and publication.

type PersistedSnapshotRefLinkProvider added in v0.21.0 

type PersistedSnapshotRefLinkProvider interface {
	PersistedSnapshotRefLinks() []PersistedSnapshotRefLink
}

PersistedSnapshotRefLinkProvider is the shared interface used by persistable self payloads to expose snapshot ref links for `result_snapshot_links`.

type PersistedSnapshotScope 

type PersistedSnapshotScope struct {
	OwnerResultID uint64
	OutputPath    PersistedRefPath
}

type PersistedTransferCodec 

type PersistedTransferCodec interface {
	NormalizeForeign(PersistedPayloadVisit) (ForeignPayload, error)
	ValidateForeign(PersistedPayloadVisit) error
	MapSnapshotParts(PersistedPayloadVisit) ([]CapturedCodecOutput, error)
}

PersistedTransferCodec operates only on encoded copies, without resolving schemas, operations, result references or storage.

type PreparedPartStore 

type PreparedPartStore interface {
	TryLock() bool
	Publish()
	Unlock()
}

PreparedPartStore contains only precomputed assignments. TryLock must not block or evaluate, and Publish cannot fail, allocate storage or run cleanup.

type PreparedReadyPart 

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

func (*PreparedReadyPart) Release 

func (p *PreparedReadyPart) Release(ctx context.Context) error

type ReadyPartReceipt 

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

type RecipeClassification 

type RecipeClassification struct {
	NotReplayable *NotReplayableCall
}

RecipeClassification describes the structural replay properties of a recipe. A nil NotReplayable means every field reachable through the inputs that recipe loading evaluates is replayable.

type RecipeIDable added in v0.21.0 

type RecipeIDable interface {
	// RecipeID returns the semantic recipe ID of the value.
	RecipeID(context.Context) (*call.ID, error)
}

type RemoteCacheBridge 

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

RemoteCacheBridge is one attachment's renewal mailbox. Its state is guarded by the owning content source's mutex M, which also serializes attachment. M is never nested with the graph, gate, lazy, payload or demand mutexes.

func (*RemoteCacheBridge) ReplyRenewal 

func (b *RemoteCacheBridge) ReplyRenewal(reply RenewalReply) RenewalReplyDisposition

ReplyRenewal publishes a valid reply for a live exchange. Late, duplicate, old-epoch, wrong-content and invalid replies are discarded without effect; a rejected reply leaves the exchange eligible until its original deadline. A reply for a canceled requester is discarded and retires the exchange.

func (*RemoteCacheBridge) TakeRenewalRequest 

func (b *RemoteCacheBridge) TakeRenewalRequest(ctx context.Context) (*RenewalRequest, error)

TakeRenewalRequest delivers each queued request once, retiring requests whose requester is canceled. Only the integration's consumer blocks here; canceling a Take does not cancel delivered exchanges.

type RemoteChange 

type RemoteChange struct {
	Candidates []HolderKey
	Recipes    []digest.Digest
	// contains filtered or unexported fields
}

RemoteChange is what one operation on the Cloud cache's holdings changed, for the service to act on. Candidates are the holdings it created or released an owner of, for the next CollectRemoteHoldings: no operation collects by itself. Recipes are the recipe digests of the entries whose reconciliation it may change: an entry it created or gave a new holding, one whose holding's parts, count or expiry it changed, and every entry it joined to another class of entries, directly or by congruence (trackJoinsLocked). A recipe digest names the entry's class whenever EquivalentHolders reads it, whatever renumbering the classes had in between.

type RemoteEntryInfo 

type RemoteEntryInfo struct {
	// Number is the entry's number in this cache.
	Number uint64
	// Stored reports that the entry stores a record, a value of its own, and
	// StoredExpiresAtUnix is that record's own expiry (0: none, or no
	// record).
	Stored              bool
	StoredExpiresAtUnix int64
	Field               string
	// Recipes are the recipe digests that name the entry.
	Recipes []digest.Digest
	// Digests are the digests the entry is posted under.
	Digests []string
	// ClassDigests are every digest of the entry's equivalence classes.
	ClassDigests []string
	// Terms are the terms producing the entry's classes, each over its inputs'
	// class representatives (the smallest digest of each input class), sorted.
	Terms    []RemoteTerm
	Holdings []RemoteHoldingInfo
}

RemoteEntryInfo describes an entry and every holding on it.

type RemoteHolding 

type RemoteHolding struct {
	// Recipe is the recipe digest of the entry's stored call frame
	// (dag.output); the holding sits on the entry of that recipe.
	Recipe digest.Digest
	// Request is the digest of the call that returned the entry (dag.digest),
	// taught onto the entry as an equivalence when it differs from Recipe.
	Request digest.Digest
	// Field is the name of the call's field, for description.
	Field string
	// Term is the call's structural term, when the call derived one.
	Term *RemoteTerm
	// ContentDigest is the entry's content digest, when known.
	ContentDigest digest.Digest
	// TypeName is the name of the entry's type.
	TypeName string
	// ExpiresAtUnix is the entry's own expiry in its cache (0: none).
	ExpiresAtUnix int64
	// Deps are the result numbers of the entry's dependencies in its cache.
	Deps []uint64
	// Parts are the entry's complete parts in its cache.
	Parts []PersistedPartAddress
	// Replacements is the entry's replacement count in its cache, read with
	// the value state above; it orders that state (HeldValueState).
	Replacements uint64
	// Executed reports that the call computed the entry, as the service
	// counts executed evidence: once the cache has dropped a value, only a
	// computation after the drop may bring it back (holding.executed).
	Executed bool
	// UsedAtUnixNano is when the span was recorded where the service read
	// it, a use of the entry (0: unknown). The entry's last use never moves
	// back.
	UsedAtUnixNano int64
}

RemoteHolding describes one engine cache's entry as one of its call spans reports it.

type RemoteHoldingInfo 

type RemoteHoldingInfo struct {
	Key                    HolderKey
	TypeName               string
	ContentDigest          digest.Digest
	ExpiresAtUnix          int64
	Retained               bool
	RetentionExpiresAtUnix int64
	Sessions               []string
	Deps                   []uint64
	UnknownDeps            []uint64
	Dependents             int
	// Parts are the copy's complete parts, and OfferedParts the ones its
	// cache has an offer of and not the bytes.
	Parts        []PersistedPartAddress
	OfferedParts []PersistedPartAddress
	// Replacements is the counterpart's replacement count the value state
	// describes.
	Replacements uint64
	// Executed reports that the holding's cache computed the entry since
	// the cache last dropped the entry's value (RemoteHolding.Executed).
	Executed bool
}

RemoteHoldingInfo describes one holding.

type RemoteHoldingUpdate 

type RemoteHoldingUpdate struct {
	ContentDigest digest.Digest
	Deps          []uint64
	Parts         []PersistedPartAddress
	Replacements  uint64
}

RemoteHoldingUpdate is what a later report adds to an existing holding: the parts an evaluation completed, the content digest it learned and the dependencies it added, at the entry's replacement count.

type RemoteTerm 

type RemoteTerm struct {
	Self   digest.Digest
	Inputs []digest.Digest
}

RemoteTerm is an operation's self digest over its ordered structural inputs.

type RenewalReply 

type RenewalReply struct {
	ID          RenewalRequestID
	Chain       digest.Digest
	Unavailable bool
	Addresses   map[digest.Digest]BlobAddress
}

type RenewalReplyDisposition 

type RenewalReplyDisposition uint8
const (
	RenewalReplyDiscarded RenewalReplyDisposition = iota
	RenewalReplyAccepted
)

type RenewalRequest 

type RenewalRequest struct {
	ID RenewalRequestID
	// Chain is the fingerprint of the exact copied ordered layers.
	Chain      digest.Digest
	RenewalKey string
	// Layers is an immutable copy with no result or owner runtime IDs.
	Layers     []snapshots.ExportLayer
	NeededBlob digest.Digest
	Deadline   time.Time
	// Done closes on cancellation, timeout, accepted reply, detach or shutdown.
	Done <-chan struct{}
}

type RenewalRequestID 

type RenewalRequestID struct {
	Epoch    [16]byte
	Sequence uint64
}

type Result added in v0.18.13 

type Result[T Typed] struct {
	// contains filtered or unexported fields
}

func NewResultForCall added in v0.21.0 

func NewResultForCall[T Typed](
	self T,
	call *ResultCall,
) (res Result[T], _ error)

NewResultForCall creates a new Result with the given call and self value.

func NewResultForCurrentCall added in v0.21.0 

func NewResultForCurrentCall[T Typed](
	ctx context.Context,
	self T,
) (Result[T], error)

NewResultForCurrentCall creates a new Result that's set to the current call from the given self value.

func (Result[T]) ContentPreferredDigest added in v0.21.0 

func (r Result[T]) ContentPreferredDigest(ctx context.Context) (digest.Digest, error)

func (Result[T]) DerefValue added in v0.18.13 

func (r Result[T]) DerefValue() (AnyResult, bool)

func (Result[T]) HitCache added in v0.20.0 

func (r Result[T]) HitCache() bool

func (Result[T]) ID added in v0.18.13 

func (r Result[T]) ID() (*call.ID, error)

ID returns the runtime handle ID of the instance.

func (Result[T]) MarshalJSON added in v0.18.13 

func (r Result[T]) MarshalJSON() ([]byte, error)

func (Result[T]) NthValue added in v0.18.13 

func (r Result[T]) NthValue(ctx context.Context, nth int) (ret AnyResult, rerr error)

func (Result[T]) NullableWrapped added in v0.21.0 

func (r Result[T]) NullableWrapped() AnyResult

func (Result[T]) RecipeDigest added in v0.21.0 

func (r Result[T]) RecipeDigest(ctx context.Context) (digest.Digest, error)

func (Result[T]) RecipeID added in v0.21.0 

func (r Result[T]) RecipeID(ctx context.Context) (*call.ID, error)

func (Result[T]) ResultCall added in v0.21.0 

func (r Result[T]) ResultCall() (*ResultCall, error)

func (Result[T]) Self added in v0.18.13 

func (r Result[T]) Self() T

func (Result[T]) SetField added in v0.18.13 

func (r Result[T]) SetField(field reflect.Value) error

func (Result[T]) String added in v0.18.13 

func (r Result[T]) String() string

String returns the instance in Class@sha256:... format.

func (Result[T]) Type added in v0.18.13 

func (r Result[T]) Type() *ast.Type

func (Result[T]) Unwrap added in v0.18.13 

func (r Result[T]) Unwrap() Typed

Unwrap returns the inner value of the instance.

func (Result[T]) WithContentDigest added in v0.19.11 

func (r Result[T]) WithContentDigest(ctx context.Context, contentDigest digest.Digest, additionalLabels ...string) (Result[T], error)

WithContentDigest sets the content identity and optionally attaches the same digest under additional informational labels. Existing labelled entries remain.

func (Result[T]) WithContentDigestAny added in v0.20.0 

func (r Result[T]) WithContentDigestAny(ctx context.Context, customDigest digest.Digest, additionalLabels ...string) (AnyResult, error)

WithContentDigestAny is WithContentDigest but returns an AnyResult, required for polymorphic code paths like module function call plumbing.

func (Result[T]) WithSessionResourceHandle added in v0.21.0 

func (r Result[T]) WithSessionResourceHandle(ctx context.Context, handle SessionResourceHandle) (Result[T], error)

func (Result[T]) WithSessionResourceHandleAny added in v0.21.0 

func (r Result[T]) WithSessionResourceHandleAny(ctx context.Context, handle SessionResourceHandle) (AnyResult, error)

type ResultArray added in v0.18.13 

type ResultArray[T Typed] []Result[T]

func (ResultArray[T]) Element added in v0.18.13 

func (arr ResultArray[T]) Element() Typed

func (ResultArray[T]) Len added in v0.18.13 

func (arr ResultArray[T]) Len() int

func (ResultArray[T]) Nth added in v0.18.13 

func (arr ResultArray[T]) Nth(i int) (Typed, error)

func (ResultArray[T]) NthValue added in v0.18.13 

func (arr ResultArray[T]) NthValue(i int, _ *ResultCall) (AnyResult, error)

func (ResultArray[T]) Type added in v0.18.13 

func (i ResultArray[T]) Type() *ast.Type

type ResultCall added in v0.21.0 

type ResultCall struct {
	Kind        ResultCallKind  `json:"kind"`
	Type        *ResultCallType `json:"type,omitempty"`
	Field       string          `json:"field,omitempty"`
	SyntheticOp string          `json:"syntheticOp,omitempty"`
	View        call.View       `json:"view,omitempty"`
	Nth         int64           `json:"nth,omitempty"`
	EffectIDs   []string        `json:"effectIDs,omitempty"`
	// ExtraDigests are the original extra digests explicitly attached when this
	// call/result was first created. They are useful provenance, but they are
	// not the authoritative merged digest state. The cache/e-graph remains the
	// source of truth for the full merged output-equivalence digest set.
	ExtraDigests   []call.ExtraDigest `json:"extraDigests,omitempty"`
	Receiver       *ResultCallRef     `json:"receiver,omitempty"`
	Module         *ResultCallModule  `json:"module,omitempty"`
	Args           []*ResultCallArg   `json:"args,omitempty"`
	ImplicitInputs []*ResultCallArg   `json:"implicitInputs,omitempty"`

	// ProfileSkip records that the wcprof OTel second source must NOT profile this
	// call: the reflection / schema-walk class that normal telemetry already hides
	// and that, when profiled, dominates OTel volume on a module-load workload.
	// (Native wcprof is opt-in/dev-only and keeps full detail — it ignores this bit.) It is set once, before the frame is
	// used, by core.AroundFunc from the static profileSkip(receiverType, field)
	// predicate, and it travels with the frame through clone()/fork() and JSON
	// persistence — so every singleflight joiner, every derived (nth-element) child,
	// every adopted/copied/imported result carries the producer's decision without a
	// per-site provenance audit. It is a pure function of the recipe, so it is
	// EXCLUDED from every digest (recipeDigest / contentPreferredDigest /
	// selfDigestAndInputRefs / callPB / recipeID) — two frames with the same recipe
	// necessarily agree on it, so excluding it is consistent, and it must never enter
	// callKey/callDigest/concurrencyKey. Only the OTel emit gates in cache.go read it;
	// native wcprof is opt-in/dev-only and keeps full detail (not gated). See
	// profileSkip in core/telemetry.go.
	ProfileSkip bool `json:"profileSkip,omitempty"`
	// contains filtered or unexported fields
}

func ChildFieldCall added in v0.21.0 

func ChildFieldCall(parent *ResultCall, field string, fieldType *ast.Type) *ResultCall

ChildFieldCall derives the call frame for a child field selection while preserving the receiver lineage, module, and view from the parent call.

func CurrentCall added in v0.21.0 

func CurrentCall(ctx context.Context) *ResultCall

func (*ResultCall) AllEffectIDs added in v0.21.0 

func (frame *ResultCall) AllEffectIDs() ([]string, error)

func (*ResultCall) CallPB added in v0.21.0 

func (frame *ResultCall) CallPB(ctx context.Context) (*callpbv1.Call, error)

func (*ResultCall) ContentDigest added in v0.21.0 

func (frame *ResultCall) ContentDigest() digest.Digest

func (*ResultCall) ContentPreferredDigest added in v0.21.0 

func (frame *ResultCall) ContentPreferredDigest(ctx context.Context) (digest.Digest, error)

ContentPreferredDigest is the historical runtime identity used by services and other core objects. Telemetry uses ContentPreferredDigestForTelemetry, which matches recipe encoding and observes content learned by inputs later.

func (*ResultCall) ContentPreferredDigestForTelemetry 

func (frame *ResultCall) ContentPreferredDigestForTelemetry(ctx context.Context) (digest.Digest, error)

ContentPreferredDigestForTelemetry prefers this operation's recorded content digest. Otherwise it uses recipe encoding with recursively content-preferred result inputs. With no recorded content anywhere, it equals RecipeDigest.

This is an observation of currently available content: it neither evaluates results nor canonicalizes e-graph equivalences. Non-content extra digests are ignored. Unlike the historical runtime ContentPreferredDigest, it does not retain a memo across observations, since inputs may learn content later.

func (*ResultCall) Inputs added in v0.21.0 

func (frame *ResultCall) Inputs(ctx context.Context) ([]digest.Digest, error)

func (*ResultCall) ReceiverCall added in v0.21.0 

func (frame *ResultCall) ReceiverCall(ctx context.Context) (*ResultCall, error)

func (*ResultCall) RecipeDigest added in v0.21.0 

func (frame *ResultCall) RecipeDigest(ctx context.Context) (digest.Digest, error)

func (*ResultCall) RecipeID added in v0.21.0 

func (frame *ResultCall) RecipeID(ctx context.Context) (*call.ID, error)

func (*ResultCall) SelfDigestAndInputRefs added in v0.21.0 

func (frame *ResultCall) SelfDigestAndInputRefs(ctx context.Context) (digest.Digest, []ResultCallStructuralInputRef, error)

type ResultCallArg added in v0.21.0 

type ResultCallArg struct {
	Name        string             `json:"name,omitempty"`
	IsSensitive bool               `json:"isSensitive,omitempty"`
	Value       *ResultCallLiteral `json:"value,omitempty"`
}

type ResultCallKind added in v0.21.0 

type ResultCallKind string
const (
	ResultCallKindField     ResultCallKind = "field"
	ResultCallKindSynthetic ResultCallKind = "synthetic"
)

type ResultCallLiteral added in v0.21.0 

type ResultCallLiteral struct {
	Kind ResultCallLiteralKind `json:"kind"`

	BoolValue   bool    `json:"boolValue,omitempty"`
	IntValue    int64   `json:"intValue,omitempty"`
	FloatValue  float64 `json:"floatValue,omitempty"`
	StringValue string  `json:"stringValue,omitempty"`
	BytesValue  []byte  `json:"bytesValue,omitempty"`
	EnumValue   string  `json:"enumValue,omitempty"`

	DigestedStringValue  string        `json:"digestedStringValue,omitempty"`
	DigestedStringDigest digest.Digest `json:"digestedStringDigest,omitempty"`

	ResultRef    *ResultCallRef       `json:"resultRef,omitempty"`
	ListItems    []*ResultCallLiteral `json:"listItems,omitempty"`
	ObjectFields []*ResultCallArg     `json:"objectFields,omitempty"`
}

type ResultCallLiteralKind added in v0.21.0 

type ResultCallLiteralKind string
const (
	ResultCallLiteralKindNull           ResultCallLiteralKind = "null"
	ResultCallLiteralKindBool           ResultCallLiteralKind = "bool"
	ResultCallLiteralKindInt            ResultCallLiteralKind = "int"
	ResultCallLiteralKindFloat          ResultCallLiteralKind = "float"
	ResultCallLiteralKindString         ResultCallLiteralKind = "string"
	ResultCallLiteralKindBytes          ResultCallLiteralKind = "bytes"
	ResultCallLiteralKindEnum           ResultCallLiteralKind = "enum"
	ResultCallLiteralKindDigestedString ResultCallLiteralKind = "digested_string"
	ResultCallLiteralKindResultRef      ResultCallLiteralKind = "result_ref"
	ResultCallLiteralKindList           ResultCallLiteralKind = "list"
	ResultCallLiteralKindObject         ResultCallLiteralKind = "object"
)

type ResultCallModule added in v0.21.0 

type ResultCallModule struct {
	ResultRef *ResultCallRef `json:"resultRef,omitempty"`
	Name      string         `json:"name,omitempty"`
	Ref       string         `json:"ref,omitempty"`
	Pin       string         `json:"pin,omitempty"`
}

type ResultCallRef added in v0.21.0 

type ResultCallRef struct {
	ResultID uint64      `json:"resultID,omitempty"`
	Call     *ResultCall `json:"call,omitempty"`
	// contains filtered or unexported fields
}

func (*ResultCallRef) Validate added in v0.21.0 

func (ref *ResultCallRef) Validate() error

type ResultCallStructuralInputRef added in v0.21.0 

type ResultCallStructuralInputRef struct {
	Result *ResultCallRef
	Digest digest.Digest
}

func (ResultCallStructuralInputRef) InputDigest added in v0.21.0 

func (ref ResultCallStructuralInputRef) InputDigest(ctx context.Context) (digest.Digest, error)

func (ResultCallStructuralInputRef) Validate added in v0.21.0 

func (ref ResultCallStructuralInputRef) Validate() error

type ResultCallType added in v0.21.0 

type ResultCallType struct {
	NamedType string          `json:"namedType,omitempty"`
	NonNull   bool            `json:"nonNull,omitempty"`
	Elem      *ResultCallType `json:"elem,omitempty"`
}

func NewResultCallType added in v0.21.0 

func NewResultCallType(gqlType *ast.Type) *ResultCallType

type RetentionObservation 

type RetentionObservation struct {
	Retained      bool
	ExpiresAtUnix int64
	// Generation is the number of the engine cache's start that observed it,
	// and EngineTimeUnixNano that engine's clock when it did.
	Generation         uint64
	EngineTimeUnixNano int64
}

RetentionObservation is one observation of an entry's retention edge in its cache: set (Retained, with the edge's expiry) or dropped, at the time the engine observed it.

type Scalar added in v0.11.3 

type Scalar[T ScalarValue] struct {
	Name  string
	Value T
}

Scalar is a GraphQL scalar.

func NewScalar added in v0.11.3 

func NewScalar[T ScalarValue](name string, val T) Scalar[T]

func (Scalar[T]) DecodeInput added in v0.11.3 

func (s Scalar[T]) DecodeInput(val any) (Input, error)

func (Scalar[T]) Decoder added in v0.11.3 

func (s Scalar[T]) Decoder() InputDecoder

func (Scalar[T]) MarshalJSON added in v0.11.3 

func (s Scalar[T]) MarshalJSON() ([]byte, error)

func (Scalar[T]) ToLiteral added in v0.11.3 

func (s Scalar[T]) ToLiteral() call.Literal

func (Scalar[T]) Type added in v0.11.3 

func (s Scalar[T]) Type() *ast.Type

func (Scalar[T]) TypeDefinition added in v0.11.3 

func (s Scalar[T]) TypeDefinition(view call.View) *ast.Definition

func (Scalar[T]) TypeName added in v0.11.3 

func (s Scalar[T]) TypeName() string

func (*Scalar[T]) UnmarshalJSON added in v0.11.3 

func (s *Scalar[T]) UnmarshalJSON(p []byte) error

func (Scalar[T]) Unwrap added in v0.21.1 

func (s Scalar[T]) Unwrap() Typed

Unwrap exposes the inner scalar value so callers (e.g. UnwrapAs) can reach interfaces implemented by T — for instance, when T is AnyID, IDable is reachable through the wrapped value.

type ScalarType 

type ScalarType interface {
	Type
	InputDecoder
}

ScalarType represents a GraphQL Scalar type.

type ScalarValue added in v0.11.3 

type ScalarValue interface {
	ScalarType
	Input
}

type SchemaModuleCandidate 

type SchemaModuleCandidate struct {
	ModuleResultID uint64
	ScopedResultID uint64
}

SchemaModuleCandidate keeps the installed operational Module separate from its implementation-scoped comparison row. Only schema recovery uses it.

type SelectedChain 

type SelectedChain struct {
	Ordinal  TransferOrdinal
	Address  PersistedPartAddress
	Layers   []snapshots.ExportLayer
	Provider content.InfoReaderProvider
}

type SelectedChains 

type SelectedChains struct {
	Entries []SelectedChain
	// contains filtered or unexported fields
}

func OpenSelectedChains 

func OpenSelectedChains(ctx context.Context, capture *HeldCapturedClosure, outputs []SelectedValueOutput, cfg config.RefConfig) (_ *SelectedChains, rerr error)

func (*SelectedChains) Release 

func (chains *SelectedChains) Release(ctx context.Context) error

type SelectedValueOutput 

type SelectedValueOutput struct {
	Result  AnyResult
	Address PersistedPartAddress
}

type Selection 

type Selection struct {
	Alias          string
	Selector       Selector
	Subselections  []Selection
	TypeConditions []string
}

Selection represents a selection of a field on an object.

func (Selection) Name 

func (sel Selection) Name() string

Name returns the name of the selection, which is either the alias or the field name.

type Selector 

type Selector struct {
	Field string
	Args  []NamedInput
	Nth   int
	View  call.View
}

Selector specifies how to retrieve a value from an Result.

func (Selector) String 

func (sel Selector) String() string

type SerializedString added in v0.18.13 

type SerializedString[T any] struct {
	Self T
}

func NewSerializedString added in v0.18.13 

func NewSerializedString[T any](val T) SerializedString[T]

func (SerializedString[T]) DecodeInput added in v0.18.13 

func (SerializedString[T]) DecodeInput(val any) (Input, error)

func (SerializedString[T]) Decoder added in v0.18.13 

func (s SerializedString[T]) Decoder() InputDecoder

func (SerializedString[T]) MarshalJSON added in v0.18.13 

func (s SerializedString[T]) MarshalJSON() ([]byte, error)

func (SerializedString[T]) SetField added in v0.18.13 

func (s SerializedString[T]) SetField(v reflect.Value) error

func (SerializedString[T]) String added in v0.18.13 

func (s SerializedString[T]) String() string

func (SerializedString[T]) ToLiteral added in v0.18.13 

func (s SerializedString[T]) ToLiteral() call.Literal

func (SerializedString[T]) Type added in v0.18.13 

func (SerializedString[T]) Type() *ast.Type

func (*SerializedString[T]) UnmarshalJSON added in v0.18.13 

func (s *SerializedString[T]) UnmarshalJSON(p []byte) error

type Server 

type Server struct {

	// View is the default view that is applied to queries on this server.
	//
	// WARNING: this is *not* the view of the current query (for that, inspect
	// the current id)
	View call.View
	// contains filtered or unexported fields
}

Server represents a GraphQL server whose schema is dynamically modified at runtime.

func AttachmentResolverServer added in v0.21.9 

func AttachmentResolverServer(ctx context.Context) *Server

AttachmentResolverServer returns the dagql server recorded as the resolver for an in-progress dependency-result attachment, if any. It is a last-resort lookup for attachment hooks that need to load stored references when no other server is reachable from the context.

func CurrentDagqlServer added in v0.18.4 

func CurrentDagqlServer(ctx context.Context) *Server

func NewServer 

func NewServer[T Typed](_ context.Context, root T) (*Server, error)

NewServer returns a new Server with the given root object.

func (*Server) AddInstallHook added in v0.17.0 

func (s *Server) AddInstallHook(hook InstallHook)

Attach an install hook

func (*Server) Around 

func (s *Server) Around(rec AroundFunc)

Around installs a function to be called around every non-cached selection.

func (*Server) Canonical added in v0.20.4 

func (s *Server) Canonical() *Server

func (*Server) ClassifyRecipe 

func (s *Server) ClassifyRecipe(id *call.ID) RecipeClassification

ClassifyRecipe structurally classifies id without evaluating it. The first NotReplayable field is reported in recipe-loading traversal order. Lazy-ref arguments are carried by reference during replay, so recipes reachable only through those arguments do not affect the classification.

Classification is best-effort. Handles, malformed recipes, and fields or parent types that are not present in the current schema are not themselves classified as non-replayable. Unknown fields' arguments are treated as non-lazy, matching recipe loading behavior.

func (*Server) Complexity 

func (s *Server) Complexity(ctx context.Context, typeName, field string, childComplexity int, args map[string]any) (int, bool)

Complexity returns the complexity of the given field.

func (*Server) Exec 

func (s *Server) Exec(ctx1 context.Context) graphql.ResponseHandler

Exec implements graphql.ExecutableSchema.

func (*Server) ExecOp 

func (s *Server) ExecOp(ctx context.Context, gqlOp *graphql.OperationContext) (results map[string]any, rerr error)

func (*Server) Fork added in v0.21.0 

func (s *Server) Fork(_ context.Context, root Typed) (*Server, error)

Fork returns a new server that starts with a clone of the current server's installed schema state but with an independent root object and independently mutable object type tables.

func (*Server) InstallDirective 

func (s *Server) InstallDirective(directive DirectiveSpec)

InstallDirective installs the given Directive type into the schema.

func (*Server) InstallInterface added in v0.21.1 

func (s *Server) InstallInterface(iface *Interface, directives ...*ast.Directive) *Interface

InstallInterface installs the given Interface type into the schema. If an interface with the same name is already installed, it is returned.

func (*Server) InstallObject 

func (s *Server) InstallObject(class ObjectType, directives ...*ast.Directive) ObjectType

InstallObject installs the given Object type into the schema, or returns the previously installed type if it was already present

func (*Server) InstallScalar 

func (s *Server) InstallScalar(scalar ScalarType, filter ...ViewFilter) ScalarType

InstallScalar installs the given Scalar type into the schema, or returns the previously installed type if it was already present.

If a ViewFilter is supplied, the scalar is only emitted in the schema for views that match the filter. The scalar is always available for input decoding, regardless of view — this lets a field with version-specific visibility accept the scalar as an argument value at runtime.

func (*Server) InstallTypeDef 

func (s *Server) InstallTypeDef(def TypeDef, filter ...ViewFilter)

InstallTypeDef installs an arbitrary type definition into the schema.

func (*Server) InterfaceType added in v0.21.1 

func (s *Server) InterfaceType(name string) (*Interface, bool)

InterfaceType returns the Interface with the given name, if it exists.

func (*Server) Load 

func (s *Server) Load(ctx context.Context, id *call.ID) (AnyObjectResult, error)

Load loads the object with the given ID.

func (*Server) LoadReplayable 

func (s *Server) LoadReplayable(ctx context.Context, id *call.ID) (AnyObjectResult, error)

LoadReplayable loads an ID without evaluating NotReplayable fields. Handles remain loadable: they reference existing results rather than replaying calls.

func (*Server) LoadType added in v0.16.3 

func (s *Server) LoadType(ctx context.Context, id *call.ID) (ret AnyResult, rerr error)

func (*Server) ObjectType 

func (s *Server) ObjectType(name string) (ObjectType, bool)

ObjectType returns the ObjectType with the given name, if it exists.

func (*Server) ObjectTypeAndServerForID 

func (s *Server) ObjectTypeAndServerForID(ctx context.Context, id *call.ID) (ObjectType, *Server, bool, error)

ObjectTypeAndServerForID resolves the object type named by id and the server whose schema defines it, without evaluating the object itself. The defining server matters to callers that must retain the type's schema after switching to another schema which may not contain the type.

func (*Server) ObjectTypeForID 

func (s *Server) ObjectTypeForID(ctx context.Context, id *call.ID) (ObjectType, bool, error)

ObjectTypeForID resolves the object type named by id without evaluating the object itself. A recipe's module provenance is authoritative even when the current schema carries another version of the same named type.

func (*Server) Query 

func (s *Server) Query(ctx context.Context, query string, vars map[string]any) (map[string]any, error)

Query is a convenience method for executing a query against the server without having to go through HTTP. This can be useful for introspection, for example.

func (*Server) Resolve 

func (s *Server) Resolve(ctx context.Context, self AnyObjectResult, sels ...Selection) (map[string]any, error)

Resolve resolves the given selections on the given object.

Each selection is resolved in parallel, and the results are returned in a map whose keys correspond to the selection's field name or alias.

func (*Server) Root 

func (s *Server) Root() AnyObjectResult

Root returns the root object of the server. It is suitable for passing to Resolve to resolve a query.

func (*Server) ScalarType 

func (s *Server) ScalarType(name string) (ScalarType, bool)

ScalarType returns the ScalarType with the given name, if it exists.

func (*Server) Schema 

func (s *Server) Schema() *ast.Schema

Schema returns the current schema of the server.

func (*Server) SchemaDigest added in v0.18.11 

func (s *Server) SchemaDigest() digest.Digest

SchemaDigest returns the digest of the current schema.

func (*Server) SchemaForView added in v0.19.11 

func (s *Server) SchemaForView(view call.View) *ast.Schema

func (*Server) Select 

func (s *Server) Select(ctx context.Context, self AnyObjectResult, dest any, sels ...Selector) (rerr error)

Select evaluates a series of chained field selections starting from the given object and assigns the final result value into dest.

func (*Server) SetCanonical added in v0.20.4 

func (s *Server) SetCanonical(canonical *Server)

func (*Server) SetNodeLoader added in v0.21.1 

func (s *Server) SetNodeLoader(loader func(ctx context.Context, id *call.ID) (AnyObjectResult, error))

SetNodeLoader sets a custom loader for the node(id:) resolver. This allows the Dagger core layer to resolve IDs through a server that has all necessary module dependencies installed.

func (*Server) SetResultServerForCall added in v0.21.1 

func (s *Server) SetResultServerForCall(loader func(ctx context.Context, resultCall *ResultCall) (*Server, error))

SetResultServerForCall installs the resolver used for module-defined recipe calls and when cache reconstruction or persisted-envelope decoding encounters an object type the current server's schema does not have installed. See the field doc on Server.resultServerForCall for the full role.

func (*Server) ToSelectable added in v0.21.1 

func (s *Server) ToSelectable(ctx context.Context, val AnyResult) (AnyObjectResult, error)

ToSelectable converts an AnyResult to an AnyObjectResult if possible.

func (*Server) TypeDef 

func (s *Server) TypeDef(name string) (TypeDef, bool)

InputType returns the InputType with the given name, if it exists.

type SessionResourceCandidate added in v0.21.0 

type SessionResourceCandidate struct {
	ClientID string
	Value    any
}

type SessionResourceHandle added in v0.21.0 

type SessionResourceHandle string

type Setter 

type Setter interface {
	SetField(reflect.Value) error
}

Setter allows a type to populate fields of a struct.

This is how builtins are supported.

type SnapshotOwnerReader 

type SnapshotOwnerReader interface {
	ReadSnapshotOwner() (OutputRevision, []PersistedSnapshotRefLink, error)
}

SnapshotOwnerReader reads a coherent revision and link set while waiting on the value's publication/body latches. Only owner synchronization, outside graph locks, may use it. Capture, boot and import keep the nonblocking reads.

type SnapshotSharedPart 

type SnapshotSharedPart struct {
	ResultID     uint64
	Part         string
	Deps         []uint64
	Replacements uint64
}

SnapshotSharedPart is one part a snapshot-sharing pass completed on an entry: the entry's result number, the part's address (as a span's dagger.io/cache.parts lists it), the entry's dependencies, and the entry's replacement count, which names the value the part and dependencies belong to.

type SnapshotValue 

type SnapshotValue struct {
	Kind     string                      `json:"kind"`
	Path     string                      `json:"path,omitempty"`
	Platform *ocispecs.Platform          `json:"platform,omitempty"`
	Services []TransferredServiceBinding `json:"services,omitempty"`
}

type SourceCheck 

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

SourceCheck is private evidence; only a validated source scan can construct it.

type StoredBundleResult 

type StoredBundleResult struct {
	// Bundle has the records of the roots' closure and outputs for its parts,
	// without addresses or renewal keys.
	Bundle ValueBundle
	// Donors has, for each of Bundle.Outputs, its storing entry: the Cloud
	// entry whose stored parts hold it, the closure entry itself or, for a
	// part borrowed from its class, the donor. The service names that entry
	// in the output's RenewalKey.
	Donors []uint64
	// Gone are the roots the cache has no entry for, and NoValue the roots
	// known only through holdings.
	Gone    []uint64
	NoValue []uint64
}

StoredBundleResult is StoredBundle's answer.

type StoredPart 

type StoredPart struct {
	Number  uint64
	Address PersistedPartAddress
}

StoredPart names one stored part: the number of its entry, and its address.

type StoredState 

type StoredState struct {
	Roots []uint64
	Parts map[uint64][]PersistedPartAddress
}

StoredState is what a blob-backed cache stores: its stored roots, and each entry's stored parts, by entry number. The service rebuilds its own maps of them from it, after a restore or a prune.

type String 

type String string

String is a GraphQL String scalar.

func NewString 

func NewString(val string) String

func (String) CachePayloadBytes 

func (s String) CachePayloadBytes() int64

func (String) DecodeInput 

func (String) DecodeInput(val any) (Input, error)

func (String) Decoder 

func (String) Decoder() InputDecoder

func (String) MarshalJSON 

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

func (String) SetField 

func (s String) SetField(v reflect.Value) error

func (String) String 

func (s String) String() string

func (String) ToLiteral 

func (s String) ToLiteral() call.Literal

func (String) Type 

func (String) Type() *ast.Type

func (String) TypeDefinition 

func (s String) TypeDefinition(view call.View) *ast.Definition

func (String) TypeName 

func (String) TypeName() string

func (*String) UnmarshalJSON 

func (s *String) UnmarshalJSON(p []byte) error

type TelemetrySeenKeyStore added in v0.21.0 

type TelemetrySeenKeyStore interface {
	LoadOrStoreTelemetrySeenKey(string) bool
	StoreTelemetrySeenKey(string)
}

type TransferFixturePartEvent 

type TransferFixturePartEvent struct {
	Kind       string                     `json:"kind"`
	ResultID   uint64                     `json:"resultID"`
	Field      string                     `json:"field"`
	Address    PersistedPartAddress       `json:"address"`
	SnapshotID string                     `json:"snapshotID,omitempty"`
	Source     *TransferFixturePartSource `json:"source,omitempty"`
}

TransferFixturePartEvent is populated only after the gated fixture enables acquisition observation. It does not participate in cache decisions.

type TransferFixturePartSource 

type TransferFixturePartSource struct {
	ResultID uint64               `json:"resultID"`
	Address  PersistedPartAddress `json:"address"`
}

type TransferFixtureReport 

type TransferFixtureReport struct {
	Parts  []TransferFixturePartEvent `json:"parts,omitempty"`
	Rows   []TransferFixtureRow       `json:"rows"`
	Owners []CacheDebugOfferOwner     `json:"owners"`
}

type TransferFixtureRow 

type TransferFixtureRow struct {
	ResultID      uint64                     `json:"resultID"`
	Call          *ResultCall                `json:"call"`
	Imported      bool                       `json:"imported"`
	Persisted     bool                       `json:"persisted"`
	DependencyIDs []uint64                   `json:"dependencyIDs"`
	Offers        []PersistedPartOffer       `json:"offers"`
	OutputClasses []uint64                   `json:"outputClasses"`
	TermIDs       []uint64                   `json:"termIDs"`
	SnapshotLinks []PersistedSnapshotRefLink `json:"snapshotLinks,omitempty"`
}

type TransferOrdinal 

type TransferOrdinal uint64

TransferOrdinal names a row within a bundle. Zero denotes optional absence.

type TransferredOutput 

type TransferredOutput struct {
	Ordinal TransferOrdinal      `json:"ordinal"`
	Address PersistedPartAddress `json:"address"`
	State   string               `json:"state"`
	Value   *SnapshotValue       `json:"value,omitempty"`
	Chain   *OfferedChain        `json:"chain,omitempty"`
	Owner   *PersistedOfferOwner `json:"owner,omitempty"`
}

type TransferredRoot 

type TransferredRoot struct {
	Ordinal       TransferOrdinal `json:"ordinal"`
	ExpiresAtUnix int64           `json:"expiresAtUnix,omitempty"`
}

type TransferredServiceBinding 

type TransferredServiceBinding struct {
	ServiceResultID uint64   `json:"serviceResultID"`
	Hostname        string   `json:"hostname"`
	Aliases         []string `json:"aliases,omitempty"`
}

type TransferredValue 

type TransferredValue struct {
	Ordinal TransferOrdinal `json:"ordinal"`
	// SenderNumber is the entry's number in the sending cache. An engine that
	// imports the value keeps it as its Cloud holding's number.
	SenderNumber uint64 `json:"senderNumber"`
	// SenderReplacements is the entry's replacement count in the sending
	// cache, read with the record: it orders the value state the record
	// describes.
	SenderReplacements uint64          `json:"senderReplacements,omitempty"`
	Record             PersistedRecord `json:"record"`
	DependencyIDs      []uint64        `json:"dependencyIDs,omitempty"`
	ExpiresAtUnix      int64           `json:"expiresAtUnix,omitempty"`
}

type Type 

type Type interface {
	// TypeName returns the name of the type.
	TypeName() string
}

Type is an object that defines a new GraphQL type.

type TypeDef 

type TypeDef interface {
	Type
	Definitive
}

TypeDef is a type whose sole practical purpose is to define a GraphQL type, so it explicitly includes the Definitive interface.

type TypeResolver added in v0.21.0 

type TypeResolver interface {
	ObjectType(name string) (ObjectType, bool)
	ScalarType(name string) (ScalarType, bool)
}

TypeResolver is the minimal schema lookup surface needed by dagql cache and persisted-payload reconstruction.

type Typed 

type Typed interface {
	// Type returns the GraphQL type of the value.
	Type() *ast.Type
}

Typed is any value that knows its GraphQL type.

type ValueBundle 

type ValueBundle struct {
	Version int                 `json:"version"`
	Roots   []TransferredRoot   `json:"roots"`
	Values  []TransferredValue  `json:"values"`
	Outputs []TransferredOutput `json:"outputs,omitempty"`
}

type ValueSelection 

type ValueSelection struct {
	Roots   []AnyResult
	Outputs []SelectedValueOutput
	// LeaveOutOutputsOutsideClosure leaves out a selected output whose entry
	// the captured closure doesn't hold, instead of refusing the selection.
	LeaveOutOutputsOutsideClosure bool
}

type ViewFilter added in v0.18.6 

type ViewFilter interface {
	Contains(call.View) bool
}
var GlobalView ViewFilter = nil

GlobalView is the default global view. Everyone can see it, and it behaves identically everywhere.

type Wrapper 

type Wrapper interface {
	Unwrap() Typed
}

Wrapper is an interface for types that wrap another type.

Source Files

View all Source files

Directories

Path Synopsis
callpbv1
Package idtui provides terminal user interface frontends for Dagger operations.
 Package idtui provides terminal user interface frontends for Dagger operations.
multiprefixw
internal
ioctx
Package ioctx provides a way to pass standard input, output, and error streams through a context.Context.
 Package ioctx provides a way to pass standard input, output, and error streams through a context.Context.
pipes
points

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.