Documentation
¶
Overview ¶
Package function is the function provider: session-scoped Starlark function resources.
A function resource is content-addressable — its identity carries separate digests for the synthesized source and the compiled bytecode — and packs to a single recovery document read back through a size-validated header.
Index ¶
Constants ¶
const (
Call op.ActionName = "function.call"
)
Action-name constants for the function provider's plan-mode actions.
Each constant is the short dotted action label its method dispatches under. Pass these to plan.Plan, op.ReceiverRegistry().BuildAction, RuntimeEnvironment.ActionByName, or WithActionNamed in place of a string literal so a typo is a compile error and rename / find-references work through the constant.
Variables ¶
This section is empty.
Functions ¶
func FormatLiteral ¶
FormatLiteral serializes a frozen Starlark value as a valid Starlark source literal.
Used to inline closure bindings in synthetic files. Supports String, Int, Float, Bool, NoneType, List, Dict, Tuple, and Struct. Struct values (e.g., marshaled Resources) are serialized as dict literals with sorted keys for deterministic output.
Parameters:
- `v`: the frozen Starlark value to serialize.
Returns:
- `string`: a Starlark source literal that evaluates back to `v`.
- `error`: non-nil for types that cannot be represented as source literals (e.g., Set).
Types ¶
type Provider ¶
type Provider struct {
op.ProviderBase
}
Provider implements actions over content-addressed function resources.
The package was resource-only until phase-8 step 10 added Provider.Call — the leaf action that evaluates a callable — so a starlark function or lambda passes through planning as a *Resource and is invoked at dispatch.
func NewProvider ¶
func NewProvider(runtimeEnvironment *op.RuntimeEnvironment) *Provider
NewProvider creates a function provider bound to the given context.
func (*Provider) Call ¶
Call invokes the function `callable` with `args` and `kwargs` and returns its result.
The plan-time surface is `plan.function.call(<callable>, ...)`: a starlark function or lambda passed as the first argument crosses the bridge intact and op.ActionPlanner resolves it to a *Resource via the registry's source constructor, so the lambda lives in the graph and catalog as a content-addressed function resource. The remaining positional and keyword arguments fill the function's own parameters at the call, converted and invoked through the resource's starlarkbridge.Invoker — the semantics of a native starlark call site, including the callee's own defaults and *args / **kwargs. Phase-8 step 10 desugars a lambda `when` / `then` / `default` body to this leaf; WaitUntil's step-12 rebuild is the next consumer.
Parameters:
- `callable`: the function resource to invoke.
- `args`: positional arguments for the function, as native Go values; converted to starlark at the call.
- `kwargs`: keyword arguments for the function, as native Go values; converted to starlark at the call.
Returns:
- `any`: the function's result, converted to a native Go value.
- `error`: non-nil when the resource fails to initialize, an argument or the result cannot be converted, or the call itself fails.
+devlore:claim=deterministic
type Resource ¶
type Resource interface {
op.Resource
// Init compiles and returns the callable, rehydrating from the archived pack when the in-memory cache
// is cold.
Init(thread *starlark.Thread) (starlark.Callable, error)
// Pack returns the transport envelope — source, name, parameters, position — for the content section.
Pack() ([]byte, error)
// Unpack rebuilds a resource from a document's content section, recompiling the source.
Unpack(runtimeEnvironment *op.RuntimeEnvironment, uri string, content []byte) (op.Resource, error)
// CanConvertTo and ConvertTo project the function into a Go func type, or its archived pack into
// []byte or string.
//
// Declared here because they have an OUT-OF-PACKAGE caller — the first any sealing phase has had.
// Every earlier provider's field and method consumers turned out to be in-package or doc comments, so
// their interfaces stayed at op.Resource plus accessors. This one does not.
CanConvertTo(target reflect.Type) bool
ConvertTo(target reflect.Type) (any, error)
// contains filtered or unexported methods
}
Resource holds a starlark function extracted into a self-contained synthetic source file.
The source text and its compiled bytecode are archived in the op.RecoverySite as a single packed file (see [writeFunctionPack] for the layout).
Identity is content-addressed: the URI's <specific> is `sha256:<hex>` over the synthesized source bytes. The on-disk path follows the framework's sharded content-addressed layout, so the pack lives at <Root>/.devlore/function/resource/sha256/<hex[0:2]>/<hex>.
Compiled and CompilerVersion are in-memory caches populated by NewResource and repopulated by Resource.Init when it reads bytecode out of the pack. They are NOT persisted through JSON/YAML — the archived pack is the persistent source of truth, and fresh Init calls repopulate the caches.
Lifecycle:
- NewResource(activation, *starlark.Function) extracts metadata, synthesizes source, computes the source digest as identity, compiles, packs source+compiled into one RecoverySite entry, populates in-memory caches.
- Resource.Init(thread) returns a live starlark.Callable. Fast path uses the in-memory Compiled cache when the compiler version matches; otherwise reads the pack, and on compiler-version match loads bytecode, on mismatch recompiles the source and refreshes the caches.
Resource is this provider's resource type — the sealed interface over a compiled Starlark callable.
Sealed by an unexported marker, so the closed set of implementations is the one this package declares. The bytecode travels in the graph document's content section, so a forged function resource would be a claim about code nobody compiled.
func DiscoverResource ¶
func DiscoverResource( runtimeEnvironment *op.RuntimeEnvironment, identity any, ) (Resource, error)
DiscoverResource registers a *Resource via op.ResourceCatalog.Discover without claiming production.
Used by the framework's resource registry adapter for slot coercion (when starlark supplies a string URI and the slot expects a *function.Resource) and by callers holding a reference handle without claiming production.
Discover does not stamp a producer, so unlike NewResource it takes only `runtimeEnvironment` — no unit reference is needed.
Same identity-shape dispatch as NewResource: *starlark.Function archives content; string rehydrates metadata-only.
Nil-Catalog tolerance: returns the unlinked candidate when no catalog is present.
Parameters:
- `runtimeEnvironment`: the session runtime environment.
- `identity`: a *starlark.Function or a canonical tag URI string; same dispatch as NewResource.
Returns:
- `Resource`: canonical catalog entry, or the unlinked candidate when no catalog is present.
- `error`: unsupported identity type, synthesis/compilation failure, filesystem write failure, malformed URI, or identity construction failure.
func NewResource ¶
func NewResource[T *starlark.Function | string]( runtimeEnvironment *op.RuntimeEnvironment, producerID string, identity T, ) (Resource, error)
NewResource constructs a *Resource and claims production via op.ResourceCatalog.GetOrCreate.
Use NewResource from a producer dispatch context — typically a provider method that has received an op.ActivationRecord from the framework. The returned Resource is the canonical catalog entry, stamped with `producerID = activationRecord.CallerID.ID()` (or empty when `Unit` is nil for non-graph dispatch). Use DiscoverResource instead when the caller is not claiming production (rehydration, reference handles, the framework's slot-coercion adapter).
Identity is the SHA-256 of the synthesized source bytes. When identity is a *starlark.Function, NewResource:
- Introspects parameters and metadata.
- Synthesizes a self-contained source file via [synthesize].
- Hashes the synthesized source bytes to obtain the canonical identity.
- Compiles the source via starlark.SourceProgramOptions.
- Serializes the compiled Program via starlark.Program.Write.
- Packs source + compiled + compiler version via [writeFunctionPack].
- Writes the pack to the Resource's URI-derived SourcePath (sharded CAS path).
- Caches the compiled bytes and compiler version on the Resource for in-memory fast-path Init.
When identity is a string URI, NewResource rehydrates a metadata-only Resource (no archival; the URI alone carries the source digest).
Two callers with byte-identical synthesized source produce the same URI; the first to reach the catalog wins. The second caller's write overwrites the canonical path with byte-identical content.
Nil-Catalog tolerance: returns the unlinked candidate when no catalog is present.
Parameters:
- `runtimeEnvironment`: the session runtime environment. `Root` must be non-nil when `identity` is a *starlark.Function.
- `producerID`: the producing caller's id (`activationRecord.CallerID`), or "" for caller-less dispatch. for non-graph dispatch.
- `identity`: a *starlark.Function (archival) or a canonical tag URI string (metadata-only rehydration).
Returns:
- `Resource`: canonical catalog entry, or the unlinked candidate when no catalog is present.
- `error`: unsupported identity type, synthesis/compilation failure, filesystem write failure, malformed URI, or identity construction failure.
Source Files
Directories