Module 06

Surfaces & lowering

compile, route, view, agent, context, runtime.

Concept · grounded · RICH E4

compile

A lowering target: compile <name> -> <target>.

Worked examples

compile workspace-runtime -> varro
compile browser-contract -> helios.contracts.context-bundle

A `compile` line is `compile <name> -> <target>` at the `system` scope, parsed into a VslCompileTarget {name, target}. It does not transform source text into a binary; it names a typed artifact the lowering pass is obligated to emit. The target is drawn from a closed set — `varro` (COMPILE_TARGET_VARRO) and `helios.contracts.context-bundle` (COMPILE_TARGET_CONTEXT_BUNDLE) — so an unknown target is a spec error, not a link error. Evaluate it as a build *contract*: the pair (name, target) is the obligation, and the compiler's job is to produce a lowering plan whose target bindings discharge exactly these.

compile workspace-runtime -> varro
compile browser-contract -> helios.contracts.context-bundle

One system may declare multiple `compile` lines; `compile_targets` is a Vec, so each line adds an independent obligation rather than overriding the last. Here the same typed spec lowers to two consumers: the Varro runtime artifact and the browser context-bundle contract. Contrast with a Makefile target or a Cargo binary, where the *output path* is the unit — here the unit is a named lowering *channel* whose downstream shape is fixed by the target keyword. The compiler emits a binding-report per target; a missing or unsatisfiable target surfaces as a diagnostic before any artifact is written, which is the property that makes the spec, not the build script, load-bearing.

compile booking-runtime -> varro
# Complete the surrounding checked system.

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

route

A named helios:// resource address.

Worked examples

route spec.contract = "helios://local/mentormind/goals-experiment/spec/varro-v1-product-spec?view=detail&tab=contract&bind=auto"

A `route` is `route <name> = "<uri>"`, parsed into VslRoute {name, uri}. The name (`spec.contract`) is a stable handle a workflow can `emit`; the value is a canonical platform address. Validation enforces `uri.starts_with("helios://")` — a route whose value is not a helios:// URI is rejected with `must use a canonical helios:// URI`. The query string (`?view=...&tab=...&bind=auto`) is part of the address, selecting the rendering surface and binding mode. Read it as a typed, validated symlink into the Helios resource space, resolved by the platform, not an HTTP endpoint your server handles.

route spec.instance = "helios://local/mentormind/goals-experiment/spec/varro-v1-learner-site-instance?view=detail&tab=state&bind=auto"
route public.read = "helios://external/mentormind/varro-v1/public/read?view=detail&tab=live&bind=auto"

Both lines are VslRoute entries on the same system, but the authority segment after `helios://` (`local` vs `external`) is semantically load-bearing: `local/...` addresses the governed spec/instance space, `external/...` addresses the deployed public surface. The route does not *create* the resource — it names an address the platform resolves through the authority stack. A workflow step `emit route spec.instance` therefore publishes a handle to an authoritative location, and the resolver decides what is actually returned. Evaluate the design: by forcing every navigable target through a named, helios://-validated route, the spec makes the full reachable surface enumerable and checkable, which a free-form string URL would not.

Concept · grounded · RICH E4

view

A render binding for a doc/query selection.

Worked examples

view spec.detail for doc:varro-v1-* uses center.detail

A `view` is `view <name> for <selector> uses <target>`, parsed into VslView {name, context_selector, target}. The `for` clause is a *selector* over the resource space (`doc:varro-v1-*` — a glob over doc ids), and `uses center.detail` names the render surface the platform mounts for any match. It declares a binding, not a component: there is no JSX, no template body, no props. Read it as a routing rule in the render layer — "for any doc matching this selector, present it with the center.detail surface" — which the host evaluates when resolving a navigable address. The `uses` target is itself a named platform surface (a panel/center mode), so the view composes two pieces of the typed spec rather than inlining markup.

view spec.detail for doc:varro-v1-* uses center.detail
view spec.table for query:varro-v1-* uses center.table

Two views on one system show the selector dimension: `for doc:varro-v1-*` matches document resources, `for query:varro-v1-*` matches named query results, each routed to a different surface (`center.detail` vs `center.table`). The selector prefix (`doc:` / `query:`) is the kind of thing selected; the glob picks the instances. This is a declarative dispatch table over the render layer — the platform, not the spec author, walks it to decide how a resolved resource is shown. Evaluate against a SQL view: there is no stored query and no materialised result set here; `view` produces no data, it only states which presentation surface a class of already-resolved resources is rendered through.

Concept · grounded · RICH E4

agent

An agent binding for a doc/selection.

Worked examples

agent default for doc:varro-v1-* -> agent:software.architect

An `agent` line is `agent <kind> for <selector> -> <profile>`, parsed into VslAgentBinding {kind, context_selector, profile} where kind is the closed enum `default | alternate`. It declares which agent profile (`agent:software.architect`) the platform attaches when a resource matching `doc:varro-v1-*` is acted on. It is a binding in the spec, not a running process: nothing is spawned by this line. Read it as registering a capability assignment — "this class of docs is, by default, served by this architect profile" — that the host resolves on demand, much like a strategy registered against a type rather than a daemon you start.

agent default for doc:varro-v1-* -> agent:software.architect
agent alternate for doc:varro-v1-* -> agent:factory.independent-judge

The kind keyword is constrained to `default` or `alternate` (any other token is `invalid_agent_kind`). The same selector can carry both: `default` names the primary profile the platform reaches for, `alternate` names a second profile — here an independent judge — available for review/escalation. This encodes a separation-of-authority posture directly in the spec: the doer and the reviewer are distinct, declared bindings rather than ad-hoc convention. Evaluate it as typed dependency injection with two registered implementations keyed by role, where the host chooses which to activate per task; no concurrency or process lifecycle is implied by the declaration.

Concept · grounded · RICH E4

context

A context root binding for a system.

Worked examples

context root = "helios://local/mentormind/goals-experiment/spec/varro-v1-product-spec?view=detail&tab=contract&bind=auto"

`context root = "<uri>"` is parsed into a VslContextBinding {name: "root", value} and is *required* — a system missing `context root = ...` fails validation. It establishes the canonical address the system resolves relative to: the default view (`view=detail`), tab (`tab=contract`), and binding mode (`bind=auto`) under which the system presents when opened with no further selection. Read it as the system's base href / anchor in the Helios resource space — the one absolute point from which routes and views are interpreted — not as a runtime-scoped value passed down a call tree.

system mentormind.product.varro_v1 {
  mission "..."
  authority lane "operator:research"
  context root = "helios://local/mentormind/goals-experiment/spec/varro-v1-product-spec?view=detail&tab=contract&bind=auto"
}

The validator emits `system <name> is missing context root = ...` when the binding is absent, so `context` is not optional decoration — it is the system's mandatory anchor. Because routes must be `helios://` and views/agents are interpreted against this root, the context binding is the fixed point that makes the rest of the navigable surface well-defined. Evaluate the constraint: requiring exactly one canonical root per system removes ambiguity about where the system 'is' in the resource space, which is the same discipline as requiring an absolute base URL before any relative reference can be resolved.

Concept · grounded · RICH E4

runtime

The runtime specification block (host, commit-mode).

Worked examples

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

A `runtime <name> { ... }` block is parsed into VslRuntimeBlock {name, settings} where each interior line becomes a VslSetting {key, value}. Here `host governed` and `commit-mode host-only` are two key/value settings, not statements that execute. `host = governed` declares the system runs under governed authority (the default host mode); `commit-mode = host-only` declares mutations may be committed only by the host, not by callers — encoding preview-by-default at the runtime layer. Read it as a typed deployment/authority manifest the lowering pass reads, analogous to a declarative service descriptor, not a language runtime or VM that the spec boots.

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

The lowering layer reads settings by key: `runtime_setting(runtime, "host")` and `runtime_setting(runtime, "commit-mode")`, with `host` defaulting to `governed` when omitted. So the block is a key->value bag with known keys, and an absent key is filled by a declared default rather than being undefined. Evaluate the authority semantics encoded here: `host-only` commit-mode is what makes Varro preview-by-default — a caller can describe and review a mutation, but only the host may actually commit it. The runtime block is therefore where the spec pins its governance posture, expressed as data the compiler consumes, not as runtime behaviour the block itself performs.