Documentation
¶
Overview ¶
Package policy implements the operator-pinned execution policy used by the safe-runner pattern (M-AGENT-SAFE-RUNNER, planned v0.16.0).
A Policy is loaded from a TOML file authored by an operator and pinned at deploy time. It declares which capabilities a submitted .ail program is allowed to use. The policy admission check is a row-subset comparison against the program's declared effect row — see Check.
SPIKE STATUS: This is the M1 spike for the design doc at design_docs/planned/v0_16_0/m-agent-safe-runner.md. It implements only monomorphic admission control; parametric (open) entry-function effect rows are rejected with a clear error, which is acceptable for v1 because `main` is conventionally monomorphic.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Decision ¶
type Decision struct {
OK bool `json:"ok"`
ErrorKind ErrorKind `json:"error_kind,omitempty"`
Message string `json:"message,omitempty"`
Function string `json:"function,omitempty"`
DeclaredEffects []string `json:"declared_effects"`
AllowedCaps []string `json:"allowed_caps"`
MissingFromPolicy []string `json:"missing_from_policy,omitempty"`
}
Decision is the result of a policy admission check.
JSON shape is part of the runner contract — do not change without updating the message-schema version and the design doc at design_docs/planned/v0_16_0/m-agent-safe-runner.md.
func Check ¶
Check performs admission control: is the entry function's declared effect row permitted by the policy?
Rules (v1 / spike):
- If the row is nil (pure) or has no labels → admitted.
- If the row has a non-nil Tail (parametric / open row) → REJECT with KindParametricEntry. Rationale: an open row could instantiate to anything; admitting it would defeat the purpose of the policy. `main` is conventionally monomorphic, so this is rarely a real limitation. Documented as a v1 restriction.
- Otherwise: admit iff every label in the declared row is in policy.AllowedCaps. Lists missing labels in MissingFromPolicy.
Budgets and FS sandbox are enforced at runtime by the existing effect machinery; this function only does the static cap-subset check.
type ErrorKind ¶
type ErrorKind string
ErrorKind enumerates the structured admission failure modes. Stable JSON: do not rename without bumping the schema version in messages.
type Policy ¶
type Policy struct {
AllowedCaps []string `toml:"allowed_caps"`
FSSandbox string `toml:"fs_sandbox"`
NetAllow []string `toml:"net_allow"`
Budgets map[string]int `toml:"budgets"`
TimeoutMs int `toml:"timeout_ms"`
MaxSourceBytes int `toml:"max_source_bytes"`
AIProvider string `toml:"ai_provider"`
Entry string `toml:"entry"`
}
Policy is the operator-pinned execution policy for AI-authored programs.
Field semantics:
- AllowedCaps: closed set of effect labels permitted for the entry function's declared effect row. Empty list = deny-all (the default).
- FSSandbox: filesystem root the runner will export as AILANG_FS_SANDBOX.
- NetAllow: hostname allowlist passed to the Net effect handler.
- Budgets: per-effect operation caps.
- TimeoutMs: hard timeout for the program.
- MaxSourceBytes: cap on the submitted source size.
- AIProvider: "stub" or a model name; controls the AI effect handler.
- Entry: name of the exported function to invoke.
func DefaultPolicy ¶
func DefaultPolicy() *Policy
DefaultPolicy returns a deny-all policy. This is what an empty file decodes to (TOML zero value) — the default is intentionally restrictive.
func Load ¶
Load reads and parses a policy file from disk.
Errors fall into two buckets:
- I/O errors (missing file, unreadable) — returned wrapped
- TOML errors (bad syntax, type mismatch) — returned wrapped with line info where BurntSushi provides it
Unknown fields are surfaced as a separate error so a typo in the policy file fails loudly instead of silently being ignored — A4 (explicit authority).
func (*Policy) AllowedSet ¶
AllowedSet returns the AllowedCaps slice as a set for O(1) membership tests.
Source Files