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
- func FormatLiteral(v starlark.Value) (string, error)
- type Provider
- type Resource
- func (f *Resource) CanConvertTo(target reflect.Type) bool
- func (f *Resource) ConvertTo(target reflect.Type) (any, error)
- func (f *Resource) Init(thread *starlark.Thread) (starlark.Callable, error)
- func (f *Resource) Pack() ([]byte, error)
- func (f *Resource) Unpack(runtimeEnvironment *op.RuntimeEnvironment, uri string, content []byte) (op.Resource, error)
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.
+devlore:access=planned
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.
type Resource ¶
type Resource struct {
mem.Resource
// Compiled is the starlark bytecode cached in-memory. Not persisted — the pack in RecoverySite carries the
// canonical bytes, and Init rehydrates this cache from the pack.
Compiled []byte `json:"-" yaml:"-"`
// CompilerVersion is [starlark.CompilerVersion] at the time Compiled was produced. Not persisted; paired with
// the in-memory cache.
CompilerVersion uint32 `json:"-" yaml:"-"`
// FuncName is the function name in the synthetic file (the original name, or "_lambda" for anonymous defs).
// Persisted in the in-memory marshaled shape but not load-bearing for identity.
FuncName string
// ParamNames is the ordered list of parameter names extracted from the original function.
ParamNames []string
// NumParams is the total parameter count (for validation against bridge target signatures).
NumParams int
// OriginalPos is the source position the function was extracted from (diagnostics only, e.g.,
// "recipe.star:42").
OriginalPos string
// contains filtered or unexported fields
}
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 mem's sharded CAS formula via the embedded mem.Resource, 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.
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.
func (*Resource) CanConvertTo ¶
CanConvertTo implements op.SourceConverter.
Parameters:
- `target`: destination Go type.
Returns:
- `bool`: true when target is a Go func type, or when the embedded mem.Resource can convert to target.
func (*Resource) ConvertTo ¶
ConvertTo implements op.SourceConverter.
Converts to any Go func type by building a bridge that converts arguments, calls the underlying starlark function, and converts the result. The starlark function's parameter count must match the Go func's input count. Varargs and kwargs are rejected. The Go func may return (), (T), (error), or (T, error). For non-func targets, delegates to the embedded mem.Resource's ConvertTo (which projects content to []byte or string).
Parameters:
- `target`: the Go type to convert to.
Returns:
- `any`: a Go function of the target type, or the projected content for []byte / string targets.
- `error`: non-nil if the target is not supported, the signature doesn't match, or the underlying call fails.
func (*Resource) Init ¶
Init loads the compiled program, executes its toplevel, and returns the named function as a callable.
Fast path: if Resource.Compiled is non-empty and Resource.CompilerVersion matches the runtime's starlark.CompilerVersion, the program loads directly from the in-memory cache. This is the common case within a process.
Fallback path: opens the pack from RecoverySite via mmap, inspects the header, and either (a) loads bytecode from the compiled section when the compiler version matches, or (b) reads the source section, recompiles, and caches the new bytecode on the Resource. Both sub-paths refresh the in-memory Compiled cache so subsequent Init calls in the same process stay on the fast path.
Parameters:
- `thread`: the starlark thread for program initialization.
Returns:
- `starlark.Callable`: the live function.
- `error`: non-nil if loading, compiling, or initialization fails.
func (*Resource) Pack ¶
Pack implements op.Packer, overriding the embedded mem.Resource implementation.
The transportable content is a [transportEnvelope]: the callable's metadata (FuncName, ParamNames, OriginalPos) plus the synthesized source read back from the archived pack. The raw pack file would be the wrong payload — it carries bytecode (host-specific, recompiled on the target) and no function name, and its digest is not the identity (the URI's SHA-256 covers the source bytes alone). Fixed-field JSON keeps the envelope deterministic, so pack → unpack → pack round-trips byte-identical.
Returns:
- `[]byte`: the JSON-encoded [transportEnvelope].
- `error`: missing pack (a URI-only rehydrated resource with no local archive), or a read failure.
func (*Resource) Unpack ¶
func (f *Resource) Unpack(runtimeEnvironment *op.RuntimeEnvironment, uri string, content []byte) (op.Resource, error)
Unpack implements op.Unpacker, overriding the embedded mem.Resource implementation.
Decodes the [transportEnvelope] and rebuilds the resource from its source text via [newFromSource] — compiling fresh bytecode for this host and archiving the pack into the local content-addressed store. The receiver carries no state (graph load dispatches Unpack on a zero value resolved from the URI fragment's type id). The rebuilt URI must equal `uri`: identity is the SHA-256 of the source bytes, covered by the graph checksum and signature through the slot URIs, so the equality check is what catches tampered content.
Parameters:
- `runtimeEnvironment`: the session runtime environment; supplies the store root the pack materializes into.
- `uri`: the canonical tag URI recorded in the document.
- `content`: the JSON-encoded [transportEnvelope] produced by Resource.Pack.
Returns:
- `op.Resource`: the reconstructed *function.Resource, not interned in any catalog.
- `error`: envelope decode failure, compilation or store write failure, or a URI mismatch (integrity failure).
Source Files
Directories