compute

Documentation

Overview

Package compute is the sandboxed local-compute seam. A resonator's `EXEC "op://name"` is resolved at apply time to `compute://<alg>/<digest>`; at runtime the processor hands that ref here, which loads the content-addressed artifact and runs it on a registered Engine.

The engine (a wasm runtime, etc.) is an implementation detail behind the Engine interface + registry — the same extension pattern as chassis/artifact and chassis/trace. The open core ships a reference engine; additional engines self-register via a blank import without changing this package or its callers. The language a compute is authored in is a build-time concern: one engine runs any conforming artifact.

Index

• Variables
• func RegisterEngine(name string, c Constructor)
• func WithLogWriter(ctx context.Context, w io.Writer) context.Context
• func WithMetricsSink(ctx context.Context, sink func(Metrics)) context.Context
• func WithNow(ctx context.Context, t time.Time) context.Context
• type Artifact
• type Constructor
• type Engine
  • func OpenEngine(name string, cfg EngineConfig) (Engine, error)
• type EngineConfig
• type Instance
• type Limits
• type Manager
  • func NewManager(res Resolver, lim Limits) *Manager
  • func (m *Manager) Run(ctx context.Context, ref Ref, input []byte) ([]byte, error)
• type Metrics
• type Ref
  • func ParseRef(s string) (Ref, bool)
  • func ScanRefs(txcl string) []Ref
  • func (r Ref) StoreRef() string
  • func (r Ref) String() string
• type Resolver
• type Runner

Variables

var ErrNotFound = errors.New("compute: artifact not found")

ErrNotFound is returned by a Resolver when no artifact exists for a ref.

Functions

func RegisterEngine

func RegisterEngine(name string, c Constructor)

RegisterEngine adds an engine constructor. Called from an engine package's init().

func WithLogWriter

func WithLogWriter(ctx context.Context, w io.Writer) context.Context

WithLogWriter carries a writer for the guest's diagnostic output (console.*). The processor wires it to the chassis logger so console.log is visible.

func WithMetricsSink

func WithMetricsSink(ctx context.Context, sink func(Metrics)) context.Context

WithMetricsSink carries a callback invoked once per invocation with the runtime metrics. The processor wires it to the trace + logger.

func WithNow

func WithNow(ctx context.Context, t time.Time) context.Context

WithNow carries the wall-clock the guest should observe — the real time at the moment the op runs, stamped by the caller. The generic engine reads it from context rather than from any envelope, so the seam stays transport-agnostic (and tests can inject a fixed time).

Types

type Artifact

type Artifact struct {
	Alg    string
	Digest string
	Engine string
	Wasm   []byte
}

Artifact is a resolved, content-addressed compute. Wasm holds the module bytes (opaque to this package); Engine names the registered engine that runs them.

type Constructor

type Constructor func(EngineConfig) (Engine, error)

Constructor builds an Engine from resolved config.

type Engine

type Engine interface {
	Load(ctx context.Context, art Artifact) (Instance, error)
	Name() string
}

Engine runs artifacts of one kind (e.g. wasm). Load prepares an artifact for invocation; engines may cache compiled forms keyed by digest.

func OpenEngine

func OpenEngine(name string, cfg EngineConfig) (Engine, error)

OpenEngine constructs the named engine. Unknown name is an error listing what is available.

type EngineConfig

type EngineConfig struct {
	// MaxMemoryMB caps guest memory. Engines that bound memory at
	// construction (e.g. wazero's runtime memory-limit) read it here; 0
	// means "engine default".
	MaxMemoryMB int
}

EngineConfig carries backend-selecting options resolved from chassis config. Engines extend it with their own fields without breaking existing callers (same convention as artifact.StoreConfig).

type Instance

type Instance interface {
	// Invoke runs the compute: JSON bytes in, JSON bytes out, under lim.
	Invoke(ctx context.Context, input []byte, lim Limits) ([]byte, error)
	Close(ctx context.Context) error
}

Instance is a loaded, ready-to-invoke compute. Engines load per call unless they document concurrency-safe reuse.

type Limits

type Limits struct {
	MaxMemoryMB int
	MaxWall     time.Duration
	// Now is the wall-clock the guest should observe (e.g. JS Date.now()).
	// The processor sets it to the real clock at the moment the op executes,
	// passed via WithNow. Zero = frozen epoch (engine default; bare unit
	// tests). Tests may inject a fixed time here for reproducibility.
	Now time.Time
	// Stderr receives the guest's diagnostic output (console.* / writes to fd
	// 2). nil discards it. The processor wires this to the chassis logger so
	// console.log is visible.
	Stderr io.Writer
	// MetricsSink, if set, is called once per invocation with the runtime
	// measurements (wall time, memory, exit status). The processor wires it to
	// the trace + logger. nil = no metrics.
	MetricsSink func(Metrics)
}

Limits bound a single compute invocation. Zero values mean "engine default / unbounded"; chassis config wires real defaults.

type Manager

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

Manager is the default Runner: it resolves a ref to its artifact and runs it on the artifact's engine. Engines are opened once per name and reused (an engine owns any per-digest compile cache); a fresh Instance is loaded per invocation. Implements Runner.

func NewManager

func NewManager(res Resolver, lim Limits) *Manager

NewManager builds a Manager over a Resolver with per-invocation limits. The memory cap is also handed to engines at construction (some bound memory at runtime-creation rather than per call); the wall-clock cap is enforced per invocation.

func (*Manager) Run

func (m *Manager) Run(ctx context.Context, ref Ref, input []byte) ([]byte, error)

Run satisfies Runner: resolve → open engine → load → invoke → close.

type Metrics

type Metrics struct {
	WallMS      int64
	MemoryBytes uint32
	Status      string // "ok" | "trapped" | "wall-limit"
}

Metrics are per-invocation runtime measurements, for observability. (There is no instruction "fuel" — wazero doesn't meter instructions; wall time + memory + status are what's cheaply available.)

type Ref

type Ref struct {
	Alg    string // digest algorithm, e.g. "sha256"
	Digest string // hex content digest
}

Ref is the parsed form of a `compute://<alg>/<digest>` EXEC value.

func ParseRef

func ParseRef(s string) (Ref, bool)

ParseRef parses a `compute://<alg>/<digest>` value. ok is false for any other shape (missing scheme, missing alg, or missing digest).

func ScanRefs

func ScanRefs(txcl string) []Ref

ScanRefs returns the distinct compute refs referenced by a txcl resonator. Used at activate time to verify every referenced artifact is present before the resonator materialises into the runtime ops table.

func (Ref) StoreRef

func (r Ref) StoreRef() string

StoreRef is the artifact-store key for a compute ref: "computes/<alg>/<digest>". The runtime resolver, the admin upload endpoint, and activate-time verification all derive the key through this one helper so they can never drift.

func (Ref) String

func (r Ref) String() string

String renders the canonical `compute://<alg>/<digest>` form.

type Resolver

type Resolver interface {
	Resolve(ctx context.Context, ref Ref) (Artifact, error)
}

Resolver maps a content-addressed ref to its artifact. Backed by the compute_artifacts store; tests inject a stub. ErrNotFound when absent.

type Runner

type Runner interface {
	Run(ctx context.Context, ref Ref, input []byte) ([]byte, error)
}

Runner is the processor-facing seam: resolve a ref and run it. The processor holds one and errors loudly if a compute:// op fires while unset.