Module 07

Governance & principles

Authority stack, preview-by-default, VSL, Varro.

Concept · grounded · RICH E4

Authority Stack

The layered authority model governing who may do what.

Worked examples

# layer 1 (authoritative sources): Rust model, governance contract,
#   policy engine, knowledge graph
# layer 2 (the window):           Varro
# layer 3 (callers):              humans, agents
# invariant: if Varro and a source disagree, Varro is wrong.

The Authority Stack is a strict three-layer ordering. Authoritative sources (the Rust model, governance contract, policy engine, knowledge graph) hold truth; Varro is only a window onto them; callers sit above Varro. The load-bearing invariant is the tiebreak rule: on disagreement the source wins and Varro is by definition wrong. Evaluate the consequence — Varro holds no independent state of record, so it can be rebuilt or replaced without data loss, and you never reconcile "what Varro thinks" against "what the model thinks."

authority lane "operator:magatama-program"
authority lane "agent:helios.demonstrator-import"
authority lane "reviewer:school-whs"

At the source layer, authority is declared as named lanes inside a `system`: an operator lane, an agent lane, a reviewer lane. An action binds to a lane, so "who may do what" is data in the spec rather than scattered if-checks in code. Evaluate this against RBAC bolted on at the API edge: here the authority binding travels with the action contract through every phase of crystallisation, so the policy and the operation are co-located and co-versioned, and an unauthorised lane is a parse/governance failure, not a 403 discovered at runtime.

authority lane "operator:research"
# Complete a system where governed actions preview before commit.

system mentormind.facilities.room_booking {
  mission "Specify a governed room-booking surface for a campus, exposing booking state as typed contracts under research authority"
  authority lane "operator:research"
  domain education
  maturity draft

  context root = "helios://local/mentormind/facilities/room-booking?view=detail&tab=contract&bind=auto"

  enum RoomState {
    value free
    value held
    value booked
  }

  type Room {
    field room_id: string required
    field capacity: integer required
    field state: RoomState required
  }

  compile booking-runtime -> varro

  action hold-room {
    risk low
    binding required
    input room_id: string required
  }

  query rooms.free {
    output Room[]
  }

  workflow reserve-room {
    inspect selection
    resolve rooms.free
    check hold-room
    render center.detail
  }

  runtime specification {
    host governed
    commit-mode host-only
  }
}

Concept · grounded · RICH E4

preview-by-default

Default-safe principle: actions preview before they commit.

Worked examples

$ varro run parse-paper --source paper.pdf
# PREVIEW: action parse-paper (risk low, binding required)
#   authority: agent:helios.demonstrator-import
#   would write: parsed_paper, round_trip_input
# re-run with --execute to commit
$ varro run parse-paper --source paper.pdf --execute

Preview-by-default means a mutating command (`run`, `create`) first renders the intended action, its risk class, and its authority posture, and commits nothing; the write happens only when `--execute` is supplied. This is the inverse of the usual CLI default where the command runs and `--dry-run` is opt-in. Evaluate the safety property: the safe path is the default path, so an agent or human cannot mutate by forgetting a flag — they can only mutate by adding one.

varro ask system status      # read, runs directly
varro show gate.round_trip    # read, runs directly
varro create demonstrator x   # mutate -> previews first

Preview-by-default applies only to the mutating half of the five-verb grammar. `ask`/`show`/`check` are read-only and return immediately; `run`/`create` describe the governed action and its review/authority posture before committing. The asymmetry is deliberate: the gate is on state change, not on interaction. Compare a transactional DB shell where every statement is in an implicit transaction until COMMIT — here the COMMIT (`--execute`) is explicit and per-command, and reads are never in scope for it.

Concept · grounded · RICH E4

VSL

Varro Specification Language: the typed contract language.

Worked examples

system mentormind.product.varro_v1 {
  mission "..."
  authority lane "operator:research"
  domain education
  maturity draft
  compile workspace-runtime -> varro
}

VSL (Varro Specification Language) is a declarative layer for the checkable structure of a system (its types, enums, workflows, views, and bootstrap descriptors) — explicitly distinct from the five-verb interaction grammar (`ask`, `show`, `check`, `run`, `create`). A `system` block is the top-level VSL unit, carrying identity, mission, authority, domain, and compile targets. There are no statements that execute; every line is a typed declaration the parser turns into a VslSystem with vecs of types/routes/views/agents/contexts/compile_targets/runtimes. Read VSL as a schema-and-contract language whose 'output' is a checked, lowerable specification, not an imperative program.

system mentormind.product.varro_v1 {
  maturity draft
}

Every VSL document carries a maturity rung from the closed ladder `draft -> checked -> bound -> hardened` (VslMaturity::{Draft, Checked, Bound, Hardened}). The rung is part of the contract, not metadata: `draft` permits unresolved references and inferred defaults, while higher rungs progressively forbid them. This makes VSL a language with a built-in soundness dial — the same source is held to a stricter standard as it climbs. Evaluate the consequence for tooling: a derived knowledge graph can be *capped* at the source's VslMaturity, so a claim can never be presented as more settled than the spec it came from. The maturity keyword is thus a first-class typing of confidence, native to the language.

Concept · grounded · RICH E4

Varro

The specification system whose language is VSL.

Worked examples

# authority stack
# authoritative sources (Rust model, governance contract, policy engine, KG)
#   -> Varro (the window) -> callers
# if Varro and a source disagree, Varro is wrong

Varro is a governed query and control surface over the Helios platform — a system object with a conversational interface, not a chatbot or a database. The authority stack has three layers: authoritative sources (Rust model, governance contract, policy engine, knowledge graph) sit above Varro, which is the window, which sits above callers. The invariant is directional: if Varro and a source disagree, Varro is wrong by definition. Read this as a deliberate inversion of trust — Varro holds no ground truth, it only presents what the authoritative layer asserts. For a senior engineer, evaluate it as a strict read-through facade with no authoritative cache: correctness is defined by the sources, and Varro's job is faithful projection plus governed control, never substitution of its own state.

# preview-by-default
# Varro describes the intended governed action and its
# review/authority posture BEFORE any mutation; --execute is opt-in

Preview-by-default is Varro's mutation discipline: it first describes the intended governed action and its review/authority posture, and performs no mutation until `--execute` is explicitly opted in. This pairs with the runtime `commit-mode host-only` setting — the surface can plan and present a mutation, but commit authority is reserved. Evaluate the safety property: the default code path is observation, and side effects require a distinct, explicit act, which makes accidental or implicit mutation structurally impossible rather than merely discouraged. Contrast with a typical CLI/API where the call *is* the effect; here describe-then-(maybe)-execute is the built-in two-phase contract.