sys

Documentation

Overview

Context handoffs across the dispatcher chain: the replay layer hands drivers the in-flight intent identity; the flow monitor hands them the process's accumulated taint.

Package sys defines the vocabulary of the syscall boundary: a Syscall from the guest, a SyscallResult (result, yield, or failure) back, and the Dispatcher interface that turns one into the other. Authorization carries the forward-propagating approval context for replayed external tasks. This package owns no capability behavior, persistence, or replay policy — those live in concrete dispatchers and the replay decorators above it.

Index

• Constants
• func BlockedBy(taint, forbid []string) []string
• func IdempotencyKey(ctx context.Context) (string, bool)
• func NormalizeLabels(what string, labels []string) ([]string, error)
• func Taint(ctx context.Context) []string
• func WithIdempotencyKey(ctx context.Context, key string) context.Context
• func WithTaint(ctx context.Context, labels []string) context.Context
• type Authorization
• type Capability
  • func Attenuate(parent, requested []Capability) ([]Capability, error)
  • func FindCapability(grants []Capability, name string) (Capability, bool)
• type Decision
• type Dispatcher
• type Errno
• type Syscall
  • func (sc Syscall) Copy() Syscall
• type SyscallResult
  • func Fail(message string) SyscallResult
  • func FailCode(errno Errno, message string) SyscallResult
  • func Result(result json.RawMessage) SyscallResult
  • func Yield(message string) SyscallResult
  • func (r SyscallResult) Copy() SyscallResult
  • func (r SyscallResult) Errno() Errno
  • func (r SyscallResult) Labels() []string
  • func (r SyscallResult) MarshalJSON() ([]byte, error)
  • func (r SyscallResult) Message() string
  • func (r SyscallResult) Result() json.RawMessage
  • func (r SyscallResult) Status() SyscallStatus
  • func (r *SyscallResult) UnmarshalJSON(data []byte) error
  • func (r SyscallResult) WithLabels(labels ...string) SyscallResult
• type SyscallStatus

Constants

const (
	SyscallBegin  = "sys.begin"
	SyscallCommit = "sys.commit"
	// SyscallCompensate registers a deferred inverse for the open section —
	// journaled with concrete args, executed only if the revision is later
	// abandoned. SyscallAbort is the guest's own abandonment: it ends the
	// section with a rollback instead of a commit — the registered inverses
	// run newest-first, then the section retries or the process finishes.
	// Both are served by the runtime's lifecycle layer. The tape never
	// interprets these names: a journal's rollback is marked by its
	// compensation section, not by any particular call.
	SyscallCompensate = "sys.compensate"
	SyscallAbort      = "sys.abort"
	// SyscallSpawn creates a child process (sync-first: the parent's quantum
	// runs the child; a yielding child yields the parent transitively). It is
	// served by whichever spawner the assembly composes: the kernel's Spawner
	// decorator for kernel children, or the runtime's spawn router, whose
	// grant carries the manifests of the only programs the process may spawn.
	SyscallSpawn = "sys.spawn"
	// SyscallTimer schedules a relative timer. The runtime's timer layer
	// serves it below the task layer: a valid call yields a durable task the
	// application's scheduler fires when the duration elapses, resuming the
	// process from the same point. It lives in sys because the runtime itself
	// leans on it — abort-retry parks are timer tasks the runtime authors.
	SyscallTimer = "sys.timer"
	// SyscallDeclassify moves labels out of the process's taint — an explicit,
	// human-approved crossing of a label boundary (DIFC declassification).
	// The kernel's Declassifier decorator serves it below the replay layer
	// (the approved crossing is journaled); the FlowMonitor above applies
	// the taint removal when the result passes through, fresh or replayed.
	SyscallDeclassify = "sys.declassify"
	// SyscallNow and SyscallRandom are the journaled world sources: the kernel
	// pins the guest's ambient clock and RNG for determinism, so real time and
	// entropy are capabilities instead — produced host-side on first execution,
	// journaled like any completion, and replayed verbatim (the Temporal
	// workflow.Now / SideEffect pattern).
	SyscallNow    = "sys.now"
	SyscallRandom = "sys.random"
)

Reserved syscall names. Savepoint brackets are journaled as side-effect-free markers by the host: on a failed-process resume, the journal is forked just past the outermost unclosed Begin so the whole declared unit re-executes. Brackets follow stack semantics: a Commit closes the most recent open Begin.

const ABIVersion = 3

ABIVersion is the syscall wire version this kernel speaks. Guests declare it on every Syscall; the host rejects mismatches with ErrnoBadABI. Since v3 the wire encoding is the protobuf envelope in package sys/wire; the JSON tags on these types serve journals and audit rendering, not the wire.

const SyscallLabelPrefix = "syscall:"

SyscallLabelPrefix namespaces the automatic provenance the Labeler stamps on every result ("syscall:<name>"). It is reserved: a manifest may not declare a label in this namespace, or a grant could forge the kernel's own provenance.

Functions

func BlockedBy

func BlockedBy(taint, forbid []string) []string

BlockedBy returns the sorted intersection of a call's forbidden labels and the process's accumulated taint (Taint) — the labels a self-classifying driver must refuse to let flow into this operation. Empty means the sink is clear. A driver checks this before its side effect; the kernel FlowMonitor performs the same check for any capability-wide Forbid it declares.

func IdempotencyKey

func IdempotencyKey(ctx context.Context) (string, bool)

IdempotencyKey returns the intent identity for the in-flight syscall. Drivers performing effects should hand it to the effect side (or dedup on it) so an at-least-once retry of an open intent does not double-execute.

func NormalizeLabels

func NormalizeLabels(what string, labels []string) ([]string, error)

NormalizeLabels canonicalizes a declared label set (a capability's source classes, or the sink labels it forbids): trim, drop empties, de-duplicate, and sort so journal digests are deterministic. A label in the reserved SyscallLabelPrefix namespace is rejected — that provenance is the kernel's to stamp, never the manifest's to claim. An empty set normalizes to nil. `what` names the field for the error message ("labels", "taints").

func Taint

func Taint(ctx context.Context) []string

Taint returns the process's accumulated taint. Drivers that *store* guest- derived data (e.g. tenant memory) persist it with the value, so the data's provenance survives into later sessions instead of being laundered.

func WithIdempotencyKey

func WithIdempotencyKey(ctx context.Context, key string) context.Context

WithIdempotencyKey attaches the intent identity of the in-flight syscall — (process, position, call-hash) — to the dispatch context. The replay layer sets it before delegating; it is stable across crash-retries of the same intent.

func WithTaint

func WithTaint(ctx context.Context, labels []string) context.Context

WithTaint attaches the process's accumulated taint — every label it has observed so far — to the dispatch context. The flow monitor sets it before delegating; because the guest is opaque, anything the process emits (including a value it writes to shared memory) may derive from any of these labels.

Types

type Authorization

type Authorization struct {
	Decision Decision        `json:"decision,omitempty"`
	Data     json.RawMessage `json:"data,omitempty"`
	Actor    string          `json:"actor,omitempty"`
	Reason   string          `json:"reason,omitempty"`
}

Authorization is the forward-propagating security context for a replayed external task. When the runtime replays an approved task it populates this value and passes it to every Dispatch call; on a fresh syscall it is zero.

type Capability

type Capability struct {
	Name        string          `json:"name"`
	Description string          `json:"description"`
	InputSchema json.RawMessage `json:"input_schema"`
	// Hidden keeps a capability dispatchable but excluded from the program's
	// discoverable tool menu (e.g. the LLM cognition tool the program calls by a
	// name it already knows).
	Hidden bool `json:"hidden,omitempty"`
	// Labels are the source classes this capability's results carry (e.g.
	// "untrusted_web", "secret"). The provenance monitor stamps them onto
	// every result and journals them — taint tracking starts here.
	Labels []string `json:"labels,omitempty"`
	// Forbid lists labels that may not flow into this capability's args
	// (e.g. a destructive capability forbids "untrusted_web"). Because the
	// guest is opaque, flow is judged conservatively: once a process has observed
	// a label, everything it emits may derive from it.
	Forbid []string `json:"forbid,omitempty"`
}

func Attenuate

func Attenuate(parent, requested []Capability) ([]Capability, error)

Attenuate returns the requested capabilities, verifying that delegation only shrinks authority: every requested capability must exist in parent (matched by name). This is the KeyKOS/seL4 delegation law — a parent cannot grant what it does not hold. Per-capability settings lattices (e.g. allowed origins narrower than the parent's) are the granting registration's responsibility; this helper owns the name-level subset check all grants share.

func FindCapability

func FindCapability(grants []Capability, name string) (Capability, bool)

FindCapability resolves a capability by name in a grant set. Every monitor layer (validation, flow policy, labeling, delegation) answers the same question — "what does this name mean in this grant set?" — so it lives here.

type Decision

type Decision string

Decision is the outcome of an external (human-in-the-loop) task approval.

const (
	Approved  Decision = "approved"
	Completed Decision = "completed"
	Failed    Decision = "failed"
	Denied    Decision = "denied"
	Cancelled Decision = "cancelled"
)

type Dispatcher

type Dispatcher[K any] interface {
	Dispatch(ctx context.Context, cred K, syscall Syscall, auth Authorization) (SyscallResult, error)
	Capabilities() []Capability
}

Dispatcher owns policy and handler dispatch for guest syscalls.

The syscall triad: cred is *who* is calling (the host-side credential for the process — never guest-supplied), syscall is *what* is being asked, and auth is *what has been granted* for this specific call (the resolved approval context). Leaf drivers that only perform work should ignore cred; only policy decorators (validation, approval, quotas) consume it.

type Errno

type Errno string

Errno is the machine-readable failure class carried alongside the human message, so guests branch on a closed set instead of parsing prose.

const (
	ErrnoDenied      Errno = "denied"       // authorization refused the operation
	ErrnoExpired     Errno = "expired"      // a task or grant passed its deadline
	ErrnoNotFound    Errno = "not_found"    // no handler/tool/resource by that name
	ErrnoInvalidArgs Errno = "invalid_args" // request failed validation/decoding
	ErrnoTransient   Errno = "transient"    // infrastructure failure; retry may succeed
	ErrnoConflict    Errno = "conflict"     // optimistic concurrency: the expected version did not match
	ErrnoInternal    Errno = "internal"     // unclassified failure
	ErrnoBadABI      Errno = "bad_abi"      // syscall ABI version mismatch
)

type Syscall

type Syscall struct {
	Abi  int             `json:"abi"`
	Name string          `json:"name"`
	Args json.RawMessage `json:"args,omitempty"`
}

Syscall is the guest-to-host request crossing the syscall boundary.

func (Syscall) Copy

func (sc Syscall) Copy() Syscall

type SyscallResult

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

SyscallResult is the ADT returned to guest syscalls.

func Fail

func Fail(message string) SyscallResult

Fail returns an unclassified (ErrnoInternal) failure. Prefer FailCode.

func FailCode

func FailCode(errno Errno, message string) SyscallResult

FailCode returns a failure classified by errno.

func Result

func Result(result json.RawMessage) SyscallResult

func Yield

func Yield(message string) SyscallResult

func (SyscallResult) Copy

func (r SyscallResult) Copy() SyscallResult

func (SyscallResult) Errno

func (r SyscallResult) Errno() Errno

Errno returns the failure class; empty unless Status is StatusFailed.

func (SyscallResult) Labels

func (r SyscallResult) Labels() []string

Labels returns the provenance labels stamped on this result — the source classes its data derives from. Sorted and deduplicated.

func (SyscallResult) MarshalJSON

func (r SyscallResult) MarshalJSON() ([]byte, error)

MarshalJSON renders the durable/wire form without HTML escaping: the guest's result bytes must survive storage verbatim, or a restored journal would carry \u003c-escaped bytes the guest never produced.

func (SyscallResult) Message

func (r SyscallResult) Message() string

func (SyscallResult) Result

func (r SyscallResult) Result() json.RawMessage

func (SyscallResult) Status

func (r SyscallResult) Status() SyscallStatus

func (*SyscallResult) UnmarshalJSON

func (r *SyscallResult) UnmarshalJSON(data []byte) error

func (SyscallResult) WithLabels

func (r SyscallResult) WithLabels(labels ...string) SyscallResult

WithLabels returns a copy of the result carrying the union of its labels and the given ones, sorted and deduplicated (so journal digests are deterministic).

type SyscallStatus

type SyscallStatus string

SyscallStatus identifies a handler or replay result.

const (
	StatusResult SyscallStatus = "result"
	StatusYield  SyscallStatus = "yield"
	StatusFailed SyscallStatus = "failed"
)