preflight

Documentation

Overview

Package preflight is the pre-flight rung ladder: cheapest-first well-formedness checks that catch a malformed/unsafe call BEFORE it fires, so a dead branch never spawns a process or burns a model turn. Each rung is run in order and escalation only happens on a pass (unit 49). A catch is recorded as a typed hard-negative (passed cheap rung k, failed expensive rung k+1) — the self-labeling signal that trains the syscall-tuned model (unit 50).

Rungs in v0.1:

rung 0  static parse  — are the args even valid JSON? (unit 47)
rung 1  schema check  — required fields present + types match a JSON Schema
                        (unit 48)

It registers as a low-rank Adjudicator (runs before the authoritative monitor); the kernel's fold takes the most-restrictive verdict, so a rung Deny wins over a later Allow. A well-formed call returns Defer (the rung has nothing to prove).

Index

• Constants
• Variables
• type FieldType
• type Ladder
  • func New() *Ladder
  • func NewWithLimit(maxNeg int) *Ladder
  • func (l *Ladder) Adjudicate(ctx context.Context, c *abi.ToolCall) abi.Verdict
  • func (l *Ladder) Caps() []abi.Capability
  • func (l *Ladder) CatchRate() (caught, total int64, rate float64)
  • func (l *Ladder) Evicted() int64
  • func (l *Ladder) Negatives() [][]byte
  • func (l *Ladder) NegativesLen() int
  • func (l *Ladder) Schemas() map[string]Schema
  • func (l *Ladder) SetSchema(tool string, s Schema)
• type Schema

Constants

const DefaultMaxNegatives = 8192

DefaultMaxNegatives bounds the hard-negative ledger so a long-lived ladder driven by sustained malformed/adversarial traffic — precisely the workload preflight exists to catch — cannot grow negatives without bound. Every caughtAt appended a JSONL row with no removal path, so on the registered rank-10 Default ladder (it serves every tool call) this grew for the life of the process. It matches the repo's other process-lifetime ledgers (ctxmmu.DefaultMaxHeld, normgate.DefaultMaxHeld, ifc.DefaultLedgerLimit, ratelimit.defaultMaxKeys = 8192). When the cap is reached the OLDEST negatives are dropped first; the dropped rows are pure observability/training samples (the unit-50 harvest), so eviction shortens the harvest, never a verdict.

Variables

var Default = New()

Default is the registered ladder.

Types

type FieldType

type FieldType string

FieldType is a minimal JSON Schema scalar type.

const (
	TypeString FieldType = "string"
	TypeNumber FieldType = "number"
	TypeBool   FieldType = "boolean"
	TypeObject FieldType = "object"
	TypeArray  FieldType = "array"
	TypeAny    FieldType = ""
)

type Ladder

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

Ladder is the rung ladder. Construct with New; Default is registered.

func New

func New() *Ladder

New builds a ladder with the standard hard-negative-ledger bound (DefaultMaxNegatives).

func NewWithLimit

func NewWithLimit(maxNeg int) *Ladder

NewWithLimit builds a ladder whose hard-negative ledger holds at most maxNeg resident rows (oldest dropped first). A non-positive maxNeg falls back to DefaultMaxNegatives. This is the seam the leak-regression test uses to exercise eviction with a small bound.

func (*Ladder) Adjudicate

func (l *Ladder) Adjudicate(ctx context.Context, c *abi.ToolCall) abi.Verdict

Adjudicate runs the rungs cheapest-first.

func (*Ladder) Caps

func (l *Ladder) Caps() []abi.Capability

func (*Ladder) CatchRate

func (l *Ladder) CatchRate() (caught, total int64, rate float64)

CatchRate returns caught/total (unit 51).

func (*Ladder) Evicted

func (l *Ladder) Evicted() int64

Evicted reports the lifetime count of negatives dropped by the maxNeg bound.

func (*Ladder) Negatives

func (l *Ladder) Negatives() [][]byte

Negatives returns the labeled hard-negative JSONL rows still resident in the bounded ledger (the freshest ≤ maxNeg, in FIFO order), as a defensive copy so a caller can never mutate the live ledger. Semantics are unchanged from the pre-bound version except that rows evicted by the maxNeg cap are no longer present (use Evicted for the lifetime drop count).

func (*Ladder) NegativesLen

func (l *Ladder) NegativesLen() int

NegativesLen reports the current number of resident hard-negative rows in the bounded ledger (≤ maxNeg). Evicted reports how many were dropped by the bound over the ladder's lifetime. Together they make the leak fix observable: NegativesLen plateaus at the cap while Evicted climbs, instead of the resident ledger growing without bound.

func (*Ladder) Schemas

func (l *Ladder) Schemas() map[string]Schema

Schemas returns a deep copy of the installed per-tool schemas. The static tool linter (internal/toollint) reads these to check what contract the kernel actually ENFORCES at rung-1 — versus the contract a tool merely advertises to the model — and to catch a Required field whose declared type falls outside the supported subset (typeOK would silently treat it as TypeAny and never validate it). The returned maps are copies; mutating them does not affect the ladder.

func (*Ladder) SetSchema

func (l *Ladder) SetSchema(tool string, s Schema)

SetSchema installs a schema for a tool (rung-1 input).

type Schema

type Schema struct {
	Required map[string]FieldType
}

Schema is a tiny JSON-Schema subset: required keys + their expected types.