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
- func ExportedNames(scripts ...string) []string
- type Builder
- func (b *Builder) AddAlways(names ...string) *Builder
- func (b *Builder) AddConditional(name, gate string) *Builder
- func (b *Builder) AddDeprecated(names ...string) *Builder
- func (b *Builder) AddHarnessDelivered(name, provenance string) *Builder
- func (b *Builder) AddReserved(names ...string) *Builder
- func (b *Builder) AddRuntimeSpecific(runtime string, names ...string) *Builder
- func (b *Builder) Build() Manifest
- func (b *Builder) RestrictConditional(name string, runtimes ...string) *Builder
- type Exports
- type HarnessDelivered
- type Manifest
Constants ¶
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/.
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.
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 ¶
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 (*Builder) AddConditional ¶
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 ¶
AddDeprecated records variables that are deprecated and scheduled for removal in a future version.
func (*Builder) AddHarnessDelivered ¶
AddHarnessDelivered records a variable delivered by stock harness configuration, with provenance describing where the delivery happens.
func (*Builder) AddReserved ¶
AddReserved records variables reserved from harness override.
func (*Builder) AddRuntimeSpecific ¶
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) RestrictConditional ¶
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 ¶
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.