capabilityruntime

package
v0.0.0-...-9295172 Latest Latest
Warning

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

 Go to latest Published: Oct 14, 2026 License: MIT Imports: 5 Imported by: 1

Documentation

Overview

Package capabilityruntime defines the wire contract shared between N.O.R.E. and the Neuron CLI for distributing and executing external capability runtime packages.

The contract is deliberately minimal. It answers three questions:

  1. What is this artifact? (runtime.json manifest)
  2. How do I talk to the running runtime? (process/stdin protocol)
  3. What was resolved/frozen for a Deployment? (ResolvedCapabilityRuntime)

Registry, resolution, and installation machinery never lives here. Those belong to application/capabilityruntime. This package only declares the schema both sides agree on so the runtime never needs to import registry code.

Index

Constants

View Source 
const (
	// RuntimeKindProcess runs the entrypoint as an OS child process
	// communicating over gRPC via Unix domain sockets.
	RuntimeKindProcess = "process"

	// RuntimeKindWasm runs the entrypoint inside an embedded WASI runtime,
	// speaking the stdin/stdout JSON protocol.
	RuntimeKindWasm = "wasm"

	// RuntimeKindContainer runs the entrypoint inside an OCI container for
	// strong isolation. Reserved for future implementation.
	RuntimeKindContainer = "container"

	// RuntimeKindRemote runs the entrypoint on a remote capability runtime
	// host. Reserved for future implementation.
	RuntimeKindRemote = "remote"
)

Runtime kinds identify how a frozen capability runtime artifact is launched. The value stored in Manifest.Runtime.Type and RuntimeInfo.Type is one of these constants. The runtime backend registry dispatches on it to select the backend.

View Source 
const (
	// APIVersion is the schema version of every runtime.json manifest.
	APIVersion = "neuron/v1"

	// Kind is the discriminant of every runtime.json manifest.
	Kind = "CapabilityRuntime"

	// ProtocolV1 is the canonical wire protocol spoken by capability runtime
	// processes over gRPC (Unix domain sockets). Runtimes must declare this
	// (or a newer compatible protocol) in their manifest runtime.protocol.
	ProtocolV1 = "neuron/capability-runtime-v1"

	// ProtocolJSONV1 is the legacy stdin/stdout JSON protocol spoken by
	// one-shot capability runtime processes and WASI modules (WASI has no
	// socket interface, so gRPC is unavailable there). Runtimes that cannot
	// host a gRPC server MUST declare this protocol in their manifest.
	ProtocolJSONV1 = "neuron/capability-runtime-v1-json"

	// ManifestFile is the mandatory manifest file inside every capability
	// runtime package and every installed capability runtime directory.
	ManifestFile = "runtime.json"

	// InstallFile is the installation record written into an installed
	// capability runtime directory after a verified, atomic install.
	InstallFile = "install.json"

	// PlatformWasm is the portable platform key for WASM capability runtime
	// artifacts in a manifest's platforms map. It names the platform by its
	// execution boundary rather than a host GOOS-GOARCH pair, because a WASI
	// module runs on any host. All other platform keys are Neuron-owned
	// GOOS-GOARCH ids (e.g. "linux-amd64") naming native process artifacts.
	PlatformWasm = "wasm32-wasi"

	// PackageArchiveSuffix is the canonical suffix of the capability runtime
	// package archive asset:
	// <name>-<version>-capability-runtime.neuron.tar.gz. A package archive is
	// a single immutable artifact containing runtime.json at its root plus
	// every platform artifact referenced by the manifest. Registries prefer
	// it over per-platform assets; the manifest inside the archive is
	// authoritative.
	PackageArchiveSuffix = "-capability-runtime.neuron.tar.gz"
)

Protocol identifiers for the capability runtime handshake.

View Source 
const (
	// EnvProtocol declares the expected protocol version.
	EnvProtocol = "NEURON_CAPABILITY_RUNTIME_PROTOCOL"

	// EnvType is the capability runtime type (logical name) being executed.
	EnvType = "NEURON_CAPABILITY_RUNTIME_TYPE"

	// EnvVersion is the exact resolved version of the capability runtime.
	EnvVersion = "NEURON_CAPABILITY_RUNTIME_VERSION"

	// EnvSocket is the Unix domain socket path a gRPC capability runtime must
	// bind. The runtime creates the socket directory, so the capability runtime
	// never chooses this path itself.
	EnvSocket = "NEURON_CAPABILITY_RUNTIME_SOCKET"

	// EnvReady is the file a gRPC capability runtime creates once its server is
	// accepting connections. The runtime polls for this file rather than
	// sleeping, so a slow start does not become a fixed startup delay.
	EnvReady = "NEURON_CAPABILITY_RUNTIME_READY"
)

Environment variables injected into a capability runtime process by the runtime backend.

View Source 
const ResolvedCapabilityRuntimesKey = "resolved_capabilityRuntimes"

ResolvedCapabilityRuntimesKey is the wire key under which the frozen capability runtime set travels in a registered assembly's execution configurations.

The execution configuration payload is produced by the CLI and consumed by N.O.R.E., which are separate Go modules that agree only through this package. The frozen set is therefore the one part of that payload that is a cross-module contract, and its key must be declared once, here, instead of being re-spelled in a hand-maintained mirror struct on either side. Both modules pin this constant in tests: the producer asserts it marshals the key, the consumer asserts it decodes the key.

Variables

This section is empty.

Functions

func HostPlatform 

func HostPlatform() string

HostPlatform returns the GOOS-GOARCH key used to select a platform artifact from an capability runtime manifest (e.g. "linux-amd64").

func NormalizeType 

func NormalizeType(capabilityRuntimeType string) (string, error)

NormalizeType rounds a logical name to its canonical ':' form. This lets callers compare requirements across the repository naming and storage path variations.

func PackageArchiveName 

func PackageArchiveName(name, version string) string

PackageArchiveName returns the canonical name of the capability runtime package archive for a type and version: <name>-<version>-capability-runtime.neuron.tar.gz with ':' and '/' replaced by '-'. The name is informational only; the manifest inside the archive is authoritative for identity and content.

func PlatformForRuntime 

func PlatformForRuntime(runtimeType string) string

PlatformForRuntime returns the platform key under which an capability runtime of the given runtime kind is selected from a manifest's platforms map. WASM modules are portable and use the single "wasm32-wasi" key; every other kind binds the host's native GOOS-GOARCH key because a frozen artifact is always installed and executed on the machine running N.O.R.E.

func SupportedRuntimeKinds 

func SupportedRuntimeKinds() []string

SupportedRuntimeKinds returns the runtime kinds the runtime backend layer can launch.

func TypePath 

func TypePath(capabilityRuntimeType string) (string, error)

TypePath converts a logical name directly to its store-relative path, e.g. "neuron-runtime:github:read" -> "neuron-runtime/github/read".

Types

type Backend 

type Backend interface {
	// Start launches a capability runtime instance for the given
	// specification. The returned BackendInstance is ready to accept Execute
	// calls. The backend owns the instance lifecycle; the caller must call
	// Close when done.
	Start(ctx context.Context, spec BackendSpec) (BackendInstance, error)

	// BackendName returns the kind identifier (e.g. "process", "wasm").
	// This matches the runtime.type declared in capability runtime manifests.
	BackendName() string
}

Backend starts capability runtime instances and manages their lifecycle. Each runtime backend (process, wasm, container, remote) implements this interface. The backend registry dispatches to the correct backend based on the runtime.json manifest's runtime.type field.

Implementations must be safe for concurrent use. A single Backend instance may be shared across multiple capability runtime types of the same kind.

type BackendInstance 

type BackendInstance interface {
	// Execute runs one request through the capability runtime and returns
	// the result. The context controls cancellation and deadline propagation.
	Execute(ctx context.Context, req *Request) (*Response, error)

	// Health reports whether the instance is ready to accept requests.
	// A healthy instance has at least one worker available and connected.
	Health(ctx context.Context) error

	// Close gracefully shuts down the instance, draining any in-flight
	// requests. After Close returns, the instance must not be reused.
	Close(ctx context.Context) error
}

BackendInstance represents a running capability runtime. It provides the uniform execution contract regardless of whether the underlying runtime is a native process, WASM module, container, or remote host.

Instances are not safe for concurrent Execute calls unless the backend explicitly documents concurrent safety. The backend is responsible for multiplexing requests across workers.

type BackendSpec 

type BackendSpec struct {
	// Type is the logical capability runtime name (e.g. "github:read").
	Type string

	// Version is the exact resolved version.
	Version string

	// Protocol is the wire protocol the capability runtime speaks
	// (e.g. "neuron/capability-runtime-v1").
	Protocol string

	// Entrypoint is the absolute path to the binary or wasm module.
	Entrypoint string

	// RootDir is the absolute path of the installed capability runtime
	// directory.
	RootDir string

	// MaxWorkers is the maximum number of concurrent workers for this
	// capability runtime type. The backend may start fewer workers based on
	// demand. A value of 0 means the backend uses its own default.
	MaxWorkers int

	// Config carries capability-runtime-specific configuration that the
	// backend may forward to the runtime process or module.
	Config map[string]any
}

BackendSpec describes what to launch. It is derived from the frozen ResolvedCapabilityRuntime record persisted with a registered assembly.

type Manifest 

type Manifest struct {
	APIVersion   string              `json:"apiVersion"`
	Kind         string              `json:"kind"`
	Metadata     ManifestMetadata    `json:"metadata"`
	Runtime      ManifestRuntime     `json:"runtime"`
	Capabilities []string            `json:"capabilities"`
	Features     []string            `json:"features,omitempty"`
	Platforms    map[string]Platform `json:"platforms"`

	// Build and Artifact carry authoring-time hints for how this runtime's
	// payload is produced when it lives in a local source tree. They tell the
	// CLI how to materialize the artifact (build.command) and where it lands
	// (artifact.path) relative to the package directory. They are NEVER part
	// of the installed runtime contract: the installer strips them from the
	// stored runtime.json. Released packages (e.g. GitHub archives) ship
	// prebuilt artifacts and omit both.
	Build    *ManifestBuild    `json:"build,omitempty"`
	Artifact *ManifestArtifact `json:"artifact,omitempty"`
}

Manifest is the runtime.json package manifest. It describes one immutable capability runtime artifact: what it is, what launches it, which capabilities it can execute, and which platform binaries back it.

func (*Manifest) BuildCommand 

func (m *Manifest) BuildCommand() string

BuildCommand returns the authoring-time build command, or "" when the manifest ships a prebuilt artifact (or none).

func (*Manifest) HasFeature 

func (m *Manifest) HasFeature(feature string) bool

HasFeature reports whether the manifest declares the given feature; an empty feature list answers false (features are opt-in declarations).

func (*Manifest) Sanitized 

func (m *Manifest) Sanitized() *Manifest

Sanitized returns a copy of the manifest safe to persist inside an installed capability runtime: authoring-time build/artifact hints are stripped because an installed artifact has no build step. The runtime contract only carries identity, runtime, capabilities, features, and platforms.

func (*Manifest) Validate 

func (m *Manifest) Validate() error

Validate verifies the manifest conforms to the runtime.json schema.

type ManifestArtifact 

type ManifestArtifact struct {
	// Path is the artifact file or directory produced by Build.Command.
	Path string `json:"path,omitempty"`
}

ManifestArtifact locates the built payload relative to the package directory. A directory payload is copied recursively; a file payload is treated like a single binary (or archive) artifact. Distributed packages may list the release asset name here.

type ManifestBuild 

type ManifestBuild struct {
	// Command is the shell command that produces the artifact declared by
	// Artifact.Path. It runs in the package directory (the version
	// directory), inheriting the parent environment plus NEURON_PROJECT_ROOT
	// and NEURON_CAPABILITY_RUNTIME_DIR.
	Command string `json:"command,omitempty"`
}

ManifestBuild is an optional authoring-time instruction for producing a local capability runtime artifact. Distributed packages omit it.

type ManifestMetadata 

type ManifestMetadata struct {
	Name        string `json:"name"`
	Version     string `json:"version"`
	Description string `json:"description,omitempty"`
}

ManifestMetadata identifies the capability runtime artifact.

type ManifestRuntime 

type ManifestRuntime struct {
	// Type is the runtime backend kind: "process" today, "wasm", "container",
	// "remote", ... in the future. The backend dispatches on this value.
	Type string `json:"type"`

	// Entrypoint is the location of the executable relative to the installed
	// package root. For platform-specific artifacts the filesystem store
	// resolves the artifact name before writing it.
	Entrypoint string `json:"entrypoint"`

	// Protocol is the wire protocol spoken by the capability runtime
	// (neuron/capability-runtime-v1 for gRPC process runtimes,
	// neuron/capability-runtime-v1-json for stdin/stdout JSON runtimes).
	Protocol string `json:"protocol,omitempty"`

	// MaxWorkers bounds the number of concurrent worker processes the runtime
	// backend may spawn for this capability runtime. A value of 0 means the
	// backend default. Only meaningful for backends with long-lived workers
	// (process).
	MaxWorkers int `json:"maxWorkers,omitempty"`
}

ManifestRuntime describes how the capability runtime is launched.

type NameSplit 

type NameSplit struct {
	Owner        string   // e.g. "neuron-runtime"
	PathSegments []string // e.g. ["github", "read"]
}

NameSplit holds the structural components of a logical capability runtime name.

A logical name is a ':' separated path whose first segment is the registry owner and whose remaining segments are the functional path: 

"github:read"                 -> Owner: "github", PathSegments: ["read"]
"neuron-runtime:github:read"    -> Owner: "neuron-runtime", PathSegments: ["github", "read"]
"hashicorp:vault:auth"        -> Owner: "hashicorp", PathSegments: ["vault", "auth"]

func ParseType 

func ParseType(capabilityRuntimeType string) (*NameSplit, error)

ParseType decomposes a logical capability runtime name such as "neuron-runtime:github:read" or "github:read". The first segment is always the owner; at least one functional segment must follow it.

func (*NameSplit) String 

func (n *NameSplit) String() string

String renders the canonical logical name.

func (*NameSplit) ToGitHubRepo 

func (n *NameSplit) ToGitHubRepo() string

ToGitHubRepo builds the "owner/repo" string GitHub's API expects. Trailing path segments are hyphen-joined because GitHub has no nested repositories. 

"github:read"              -> "github/read"
"neuron-runtime:github:read" -> "neuron-runtime/github-read"

func (*NameSplit) ToLocalPath 

func (n *NameSplit) ToLocalPath() string

ToLocalPath builds the multi-level fileassembly path segments used under the capability runtime store. The ':' delimiters become directory separators, which is both cross-platform safe and keeps related capability runtimes grouped by owner.

type Platform 

type Platform struct {
	// Artifact is the binary/archive file name for this platform.
	Artifact string `json:"artifact"`

	// SHA256 is the checksum of the artifact. Required when the artifact is
	// distributed as a release asset.
	SHA256 string `json:"sha256,omitempty"`
}

Platform maps one host platform (GOOS-GOARCH) to its artifact.

type Request 

type Request struct {
	// Params carries the resolved execution params for the capability. Keys
	// map to the capability's declared params.
	Params map[string]any `json:"params"`
}

Request is the stdin payload handed to a one-shot capability runtime process. Runtimes read a single JSON document from stdin, execute, and write a single JSON Response document to stdout.

type ResolvedCapabilityRuntime 

type ResolvedCapabilityRuntime struct {
	// Type is the logical capability runtime name (e.g. "github:read").
	Type string `json:"type"`

	// RequestedVersion is the original constraint (e.g. "^1.0.0"). Empty when
	// the requirement was floating.
	RequestedVersion string `json:"requestedVersion,omitempty"`

	// ResolvedVersion is the exact version frozen into the deployment
	// (e.g. "1.2.0").
	ResolvedVersion string `json:"resolvedVersion"`

	// Registry is the registry that supplied the package.
	Registry string `json:"registry,omitempty"`

	// Digest is the content digest of the installed artifact (sha256:...).
	Digest string `json:"digest,omitempty"`

	// Runtime describes how to launch the artifact.
	Runtime RuntimeInfo `json:"runtime"`

	// Features declared by the capability runtime manifest.
	Features []string `json:"features,omitempty"`

	// Capabilities the capability runtime can execute.
	Capabilities []string `json:"capabilities,omitempty"`
}

ResolvedCapabilityRuntime is the frozen dependency record produced when an Assembly is compiled into a Deployment. Authoring an Assembly only declares requirements (type + constraint); this record pins the exact resolved version, registry, and content digest so a Deployment is reproducible.

N.O.R.E. consumes this record to execute capabilities without ever performing dependency resolution or installation. The record deliberately carries no host-specific paths: the installed artifact directory is derived from the artifact identity (type, version, digest) and the capability runtime store root configured on the daemon.

type Response 

type Response struct {
	// Result carries the results of the execution. Keys map to the
	// capability's declared result fields.
	Result map[string]any `json:"result"`

	// Error, when present, records a controlled failure. The runtime may
	// still exit zero after reporting an error this way; N.O.R.E. treats a
	// non-empty Error as an execution failure and surfaces it downstream.
	Error string `json:"error,omitempty"`
}

Response is the stdout payload produced by a one-shot capability runtime process. Runtimes must write exactly one JSON Response document to stdout and exit zero on success.

type RuntimeInfo 

type RuntimeInfo struct {
	Type       string `json:"type"`
	Protocol   string `json:"protocol,omitempty"`
	Entrypoint string `json:"entrypoint"`

	// MaxWorkers bounds the number of concurrent worker processes the runtime
	// backend may spawn for this capability runtime. A value of 0 means the
	// backend default.
	MaxWorkers int `json:"maxWorkers,omitempty"`
}

RuntimeInfo is the runtime portion of a frozen resolved capability runtime. It is duplicated from the package manifest so the deployment carries everything required to launch the artifact without re-reading remote metadata.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.