envmanifest

package
v0.55.0 Latest Latest
Warning

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

Go to latest
Published: Nov 10, 2026 License: Apache-2.0 Imports: 7 Imported by: 0

Documentation

Overview

Package envmanifest models the sandbox environment-variable contract: which variables the runner injects into the sandbox, under what conditions, per which runtime, which are delivered by stock harness configuration rather than the runner, which are reserved from harness override, and which are deprecated. RenderSchemas publishes the model as the JSON Schemas under docs/normative/sandbox-env/v1/.

The model carries variable names and category metadata only — never values or secrets. Rendering is deterministic by contract: sorted names, fixed key order, and a trailing newline, so regenerating the committed schemas without a source change produces byte-identical files. Version identity comes from the v1 path and the release tag in the fetch URL; the schemas carry no fullsend version, which commit-time stamping would break.

Index

Constants

View Source
const (
	// HarnessEnvSchemaFile validates a harness YAML's env blocks: no
	// env.sandbox key may be a name the runner reserves.
	HarnessEnvSchemaFile = "harness-env.schema.json"
	// EnvReferencesSchemaFile validates a reachability claim — "code running
	// under this runtime reads these variables" — and carries the full
	// contract inventory in its $defs.
	EnvReferencesSchemaFile = "env-references.schema.json"
)

The published schema files, under docs/normative/sandbox-env/v1/.

View Source
const PortableRuntime = "portable"

PortableRuntime is the env-references runtime value for code that must work under every runtime: it may rely only on the shared categories.

View Source
const SchemaBaseURI = "https://fullsend.ai/normative/sandbox-env/v1/"

SchemaBaseURI is the $id prefix of the published sandbox env schemas, matching the other normative schemas' https://fullsend.ai/normative/ identifiers. The schemas are fetched by tag URL, not from this host; the $id only names them.

Variables

This section is empty.

Functions

func ExportedNames

func ExportedNames(scripts ...string) []string

ExportedNames returns the sorted, distinct variable names the shell scripts place in a child process's environment. It recognizes three forms:

  • export statements, both "export NAME=value" and the bare re-export "export NAME";
  • prefix assignments on a command ("NAME=value cmd" and "env NAME=value cmd"), which the command's process inherits;
  • the same forms inside the script argument of "sh -c" or "bash -c", parsed recursively.

A plain assignment with no command ("NAME=value" alone, or "readonly NAME=value") is shell-local and is not reported, nor is a prefix assignment on a shell builtin ("IFS= read"). Assignment-shaped text inside a quoted value is data, not a binding, and a command substitution's exports stay in its subshell. The parser is a tokenizer, not a shell: it handles single and double quotes, backslash escapes, $(...) nesting, comments, and the ; && || | & ( ) { } newline separators, which is the subset the runner's emitters generate.

Types

type Builder

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

Builder assembles a Manifest from derived emitter output. The zero value is usable, but NewBuilder is the documented entry point.

func NewBuilder

func NewBuilder() *Builder

NewBuilder returns an empty manifest builder.

func (*Builder) AddAlways

func (b *Builder) AddAlways(names ...string) *Builder

AddAlways records variables the runner exports on every run.

func (*Builder) AddConditional

func (b *Builder) AddConditional(name, gate string) *Builder

AddConditional records a variable the runner exports only when gate holds. gate describes the condition; it is contract metadata, never a value.

func (*Builder) AddDeprecated

func (b *Builder) AddDeprecated(names ...string) *Builder

AddDeprecated records variables that are deprecated and scheduled for removal in a future version.

func (*Builder) AddHarnessDelivered

func (b *Builder) AddHarnessDelivered(name, provenance string) *Builder

AddHarnessDelivered records a variable delivered by stock harness configuration, with provenance describing where the delivery happens.

func (*Builder) AddReserved

func (b *Builder) AddReserved(names ...string) *Builder

AddReserved records variables reserved from harness override.

func (*Builder) AddRuntimeSpecific

func (b *Builder) AddRuntimeSpecific(runtime string, names ...string) *Builder

AddRuntimeSpecific records the variables a runtime emits beyond the shared set: its EnvExports statements plus the names its launch command sets. A runtime that emits nothing is recorded with an empty set rather than omitted.

func (*Builder) Build

func (b *Builder) Build() Manifest

Build returns the manifest with every category in canonical form.

func (*Builder) RestrictConditional

func (b *Builder) RestrictConditional(name string, runtimes ...string) *Builder

RestrictConditional records that the conditional variable name can reach only the listed runtimes, because only their bootstraps emit it. An unrestricted conditional variable is reachable under every runtime.

type Exports

type Exports struct {
	Always          []string
	Conditional     map[string]string
	RuntimeSpecific map[string][]string
	// ConditionalRuntimes restricts a Conditional variable to the runtimes
	// whose bootstrap can emit it. A Conditional variable with no entry
	// here is reachable under every runtime; one with an entry is
	// reachable only under the listed runtimes and never under portable.
	ConditionalRuntimes map[string][]string
}

Exports groups the runner-exported variable categories. Always and Conditional are runner-guaranteed modulo their gates; RuntimeSpecific is per-runtime and a portability gap, not a guarantee.

type HarnessDelivered

type HarnessDelivered struct {
	Provenance string
}

HarnessDelivered describes a variable delivered by stock harness configuration rather than by the runner. Such a variable is never a runner guarantee: one the runner guarantees belongs in Exports instead.

type Manifest

type Manifest struct {
	Exports          Exports
	HarnessDelivered map[string]HarnessDelivered
	Reserved         []string
	Deprecated       []string
}

Manifest is the sandbox environment-variable contract model.

func (Manifest) RenderSchemas

func (m Manifest) RenderSchemas() (map[string][]byte, error)

RenderSchemas returns the published JSON Schemas generated from m, keyed by file name. Each schema is self-contained — its $defs carry every category it needs — so a consumer validates against one fetched file with no cross-file $ref resolution. Output is deterministic: keys appear in a fixed order, names are sorted, and each file ends in a newline.

func (Manifest) Runtimes

func (m Manifest) Runtimes() []string

Runtimes returns the runtimes the manifest lists, sorted.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL