{ "concept_count": 31, "concept_graph": { "edges": [ { "from": "show", "requires": "ask" }, { "from": "check", "requires": "ask" }, { "from": "check", "requires": "show" }, { "from": "run", "requires": "check" }, { "from": "create", "requires": "run" }, { "from": "system", "requires": "create" }, { "from": "type", "requires": "system" }, { "from": "field", "requires": "type" }, { "from": "enum", "requires": "field" }, { "from": "enum", "requires": "type" }, { "from": "action", "requires": "enum" }, { "from": "action", "requires": "type" }, { "from": "workflow", "requires": "action" }, { "from": "workflow", "requires": "ask" }, { "from": "query", "requires": "workflow" }, { "from": "compile", "requires": "Crystal" }, { "from": "route", "requires": "compile" }, { "from": "view", "requires": "route" }, { "from": "agent", "requires": "view" }, { "from": "context", "requires": "agent" }, { "from": "runtime", "requires": "context" }, { "from": "draft", "requires": "query" }, { "from": "checked", "requires": "draft" }, { "from": "bound", "requires": "checked" }, { "from": "hardened", "requires": "bound" }, { "from": "Plasma", "requires": "hardened" }, { "from": "Gas", "requires": "Plasma" }, { "from": "Liquid", "requires": "Gas" }, { "from": "Solid", "requires": "Liquid" }, { "from": "Crystal", "requires": "Solid" }, { "from": "preview-by-default", "requires": "Authority Stack" }, { "from": "Authority Stack", "requires": "runtime" }, { "from": "VSL", "requires": "preview-by-default" }, { "from": "Varro", "requires": "VSL" } ] }, "concepts": [ { "checks": [ { "answer": "No. `ask` is read-only; it retrieves authoritative truth. Only `run` (execute an action) and `create` (make a new artifact) mutate, and both under preview-by-default.", "prompt": "Does the `ask` verb ever mutate state? If not, which verbs do?" } ], "citations": [ "helios-projects/project/knowledge-graphs/tools/varro/src/lib.rs", "helios-projects/project/knowledge-graphs/tools/varro/src/lib.rs#L70", "magatama/vsl/year10-demonstrator-seed.varro#L184", "mentormind-program/experiments/goals-experiment/bootstrap/glossary.md", "mentormind-program/experiments/goals-experiment/bootstrap/glossary.md#L12" ], "definition": "One of the five command verbs: request information without mutation.", "id": "concept:verb--ask", "misconceptions": [ { "citation": "mentormind-program/experiments/goals-experiment/bootstrap/glossary.md#L12", "correction": "`ask` is strictly read-only: it retrieves authoritative truth and returns it. Only `run` and `create` mutate, and only under preview-by-default.", "wrong_belief": "Learners think `ask` can modify or trigger something because it sounds like a request that gets fulfilled." } ], "module": "verbs", "name": "ask", "prerequisites": [], "worked_examples": [ { "citation": "magatama/vsl/year10-demonstrator-seed.varro#L184", "explanation": "Inside a workflow, `ask` retrieves the named subject so later steps can reason over it. It reads; it never writes. Compare the `ask education-project-root` line in import-year10-authorities.", "snippet": "ask demonstrator-import" }, { "citation": "helios-projects/project/knowledge-graphs/tools/varro/src/lib.rs#L70", "explanation": "At the command surface the grammar is closed: ask, show, check, run, create. `ask system status` queries authoritative truth and returns it; an unknown verb like `fetch` is rejected before it reaches a source.", "snippet": "ask " } ] }, { "checks": [ { "answer": "`ask` retrieves a value into the conversation; `show` renders a selection for presentation (a view or table). Same read, different intent.", "prompt": "Both `show` and `ask` are read-only. What distinguishes them?" } ], "citations": [ "helios-projects/project/knowledge-graphs/tools/varro/src/lib.rs", "helios-projects/project/knowledge-graphs/tools/varro/src/lib.rs#L74", "magatama/vsl/year10-demonstrator-seed.varro#L243", "mentormind-program/experiments/goals-experiment/bootstrap/glossary.md#L12" ], "definition": "One of the five verbs: render/display a view of state.", "id": "concept:verb--show", "misconceptions": [ { "citation": "mentormind-program/experiments/goals-experiment/bootstrap/glossary.md#L12", "correction": "`ask` retrieves a value into the conversation; `show` renders a selection for presentation (a view, a table). Both read state, but `show` carries display intent.", "wrong_belief": "Since both are read-only, learners use `show` and `ask` as synonyms." } ], "module": "verbs", "name": "show", "prerequisites": [ "ask" ], "worked_examples": [ { "citation": "magatama/vsl/year10-demonstrator-seed.varro#L243", "explanation": "`show` displays a selection without changing it. The report-demonstrator-claim-boundary workflow is built entirely from `show` steps because reporting is read-only.", "snippet": "show program-overview\nshow safety-case\nshow interface-control-document" }, { "citation": "helios-projects/project/knowledge-graphs/tools/varro/src/lib.rs#L74", "explanation": "`ask` is about obtaining the value into the conversation; `show` is about rendering it for a human or a view binding. Both are non-mutating, but `show` carries presentation intent (a table, a detail pane).", "snippet": "show " } ] }, { "checks": [ { "answer": "`check` validates an artifact against its contract and emits diagnostics; it never executes. On failure the workflow fails closed, so any following `create` or `run` does not proceed.", "prompt": "What happens in a workflow when a `check` step fails?" } ], "citations": [ "helios-projects/project/knowledge-graphs/tools/varro/src/lib.rs", "magatama/vsl/year10-demonstrator-seed.varro#L187", "magatama/vsl/year10-demonstrator-seed.varro#L203" ], "definition": "One of the five verbs: validate an artifact against its contract.", "id": "concept:verb--check", "misconceptions": [ { "citation": "magatama/vsl/year10-demonstrator-seed.varro#L187", "correction": "`check` only validates an artifact against its contract and emits diagnostics. It never executes; execution is `run`. A failing check fails closed and blocks any following create or run.", "wrong_belief": "Learners assume `check` executes the action or workflow it is validating." } ], "module": "verbs", "name": "check", "prerequisites": [ "ask", "show" ], "worked_examples": [ { "citation": "magatama/vsl/year10-demonstrator-seed.varro#L187", "explanation": "`check` runs a validation and yields pass/fail diagnostics. It mutates nothing; it asserts that an artifact conforms to its declared rules before a `create` step is allowed to proceed.", "snippet": "check conflict-policy\ncheck blocked-output-policy" }, { "citation": "magatama/vsl/year10-demonstrator-seed.varro#L203", "explanation": "A common, correct pattern: validate (`check`) every governing policy, and only then `create`. If a check fails, the workflow fails closed and the create never runs.", "snippet": "check evidence-class\ncheck promotion-gate\ncreate evidence-class-mapping" } ] }, { "checks": [ { "answer": "No. Varro is preview-by-default: `run` first describes the governed action and its authority posture. The mutation only occurs when `--execute` is opted in.", "prompt": "When you issue `run`, does the mutation happen immediately?" } ], "citations": [ "edu/varro/edukg/kg/overlay/assessments-entities.ndjson", "helios-projects/project/knowledge-graphs/tools/varro/src/lib.rs", "helios-projects/project/knowledge-graphs/tools/varro/src/lib.rs#L82", "magatama/vsl/year10-demonstrator-seed.varro#L181", "mentormind-program/experiments/goals-experiment/bootstrap/glossary.md#L31" ], "definition": "One of the five verbs: execute a governed action/workflow.", "id": "concept:verb--run", "misconceptions": [ { "citation": "mentormind-program/experiments/goals-experiment/bootstrap/glossary.md#L31", "correction": "Varro is preview-by-default: `run` first describes the governed action and its authority posture. The mutation happens only when `--execute` is opted in.", "wrong_belief": "Learners expect `run` to perform the mutation as soon as it is issued." } ], "module": "verbs", "name": "run", "prerequisites": [ "check" ], "worked_examples": [ { "citation": "helios-projects/project/knowledge-graphs/tools/varro/src/lib.rs#L82", "explanation": "`run` executes a declared action or workflow. Under preview-by-default it first describes the governed action and its authority posture; the mutation only happens when `--execute` is opted in.", "snippet": "run authorize-ignition --execute" }, { "citation": "magatama/vsl/year10-demonstrator-seed.varro#L181", "explanation": "A `run` step inside a workflow invokes a named action contract. The surrounding `check` keeps the run honest: nothing executes until the gate passes.", "snippet": "workflow promote-evidence {\n check promotion-gate\n run record-reconciliation\n}" } ] }, { "checks": [ { "answer": "Use `create` to bring a new governed artifact (a noun, e.g. a record or contract) into being; use `run` to execute an already-declared action (a verb) over existing state.", "prompt": "When do you use `create` rather than `run`?" } ], "citations": [ "helios-projects/project/knowledge-graphs/tools/varro/src/lib.rs", "helios-projects/project/knowledge-graphs/tools/varro/src/lib.rs#L87", "magatama/vsl/year10-demonstrator-seed.varro#L189", "mentormind-program/experiments/goals-experiment/bootstrap/glossary.md" ], "definition": "One of the five verbs: bring a new governed artifact into being.", "id": "concept:verb--create", "misconceptions": [ { "citation": "helios-projects/project/knowledge-graphs/tools/varro/src/lib.rs#L87", "correction": "`create` brings a new governed artifact (a noun) into being; `run` executes an already-declared action (a verb) over existing state. They are different mutations.", "wrong_belief": "Learners treat `create` and `run` as one mutating verb." } ], "module": "verbs", "name": "create", "prerequisites": [ "run" ], "worked_examples": [ { "citation": "magatama/vsl/year10-demonstrator-seed.varro#L189", "explanation": "`create` materialises a new governed record. In assert-magatama-source-of-truth it runs last, after the policies have been shown and checked, so the new artifact is born already validated.", "snippet": "create magatama-source-of-truth-rule\ncreate demonstrator-import-gate" }, { "citation": "helios-projects/project/knowledge-graphs/tools/varro/src/lib.rs#L87", "explanation": "`create` brings a new entity into existence (a record, a contract); `run` executes an already-declared action over existing state. Use `create` for nouns, `run` for verbs.", "snippet": "create " } ] }, { "checks": [ { "answer": "Identity (the dotted name), a mission, one or more authority lanes, a domain, and a maturity rung. Types, enums, and workflows live inside its braces.", "prompt": "What must a VSL `system` declaration include in its header?" } ], "citations": [ "magatama/vsl/year10-demonstrator-seed.varro#L20", "magatama/vsl/year10-demonstrator-seed.varro#L9", "mentormind-program/experiments/goals-experiment/bootstrap/glossary.md", "mentormind-program/experiments/goals-experiment/bootstrap/glossary.md#L17" ], "definition": "Top-level VSL declaration; a named governed system with mission, authority, domain, maturity.", "id": "concept:construct--system", "misconceptions": [ { "citation": "mentormind-program/experiments/goals-experiment/bootstrap/glossary.md#L17", "correction": "A VSL `system` is a governed unit: it must declare identity, mission, authority lanes, domain, and a maturity rung. It is a governance boundary, not just a code namespace.", "wrong_belief": "Learners read `system` as merely a class or module wrapper." } ], "module": "type-model", "name": "system", "prerequisites": [ "create" ], "worked_examples": [ { "citation": "magatama/vsl/year10-demonstrator-seed.varro#L9", "explanation": "Every VSL file is rooted in a `system`. It carries identity (the dotted name), a mission string, one or more authority lanes, a domain, and a maturity rung. Everything else (types, enums, workflows) lives inside its braces.", "snippet": "system magatama.seed.year10_demonstrator {\n mission \"Optionally import the Year 10 reactivity-rocket project ...\"\n authority lane \"operator:magatama-program\"\n domain propulsion.education-demonstrator-import\n maturity draft\n}" }, { "citation": "magatama/vsl/year10-demonstrator-seed.varro#L20", "explanation": "Beyond the header, a system can bind a `context root` (its helios:// home) and declare `compile` lowering targets. These tie the abstract system to a concrete resource address and an output backend.", "snippet": "system magatama.seed.year10_demonstrator {\n context root = \"helios://project/magatama/year10-demonstrator?view=detail\"\n compile varro-surface -> varro\n}" } ] }, { "checks": [ { "answer": "A `type` is a record of typed fields (name, kind, required/optional). It holds no behaviour; methods live in `action` and `workflow` declarations.", "prompt": "What does a VSL `type` contain, and can it hold methods?" } ], "citations": [ "edu/varro/edukg/kg/overlay/assessments-entities.ndjson", "magatama/vsl/year10-demonstrator-seed.varro#L126", "magatama/vsl/year10-demonstrator-seed.varro#L144", "mentormind-program/experiments/goals-experiment/bootstrap/glossary.md", "mentormind-program/experiments/goals-experiment/bootstrap/glossary.md#L19" ], "definition": "A named record of typed fields inside a system.", "id": "concept:construct--type", "misconceptions": [ { "citation": "mentormind-program/experiments/goals-experiment/bootstrap/glossary.md#L19", "correction": "A VSL `type` is a pure record of typed fields. Behaviour lives in `action` and `workflow` declarations, not inside the type.", "wrong_belief": "Learners expect a VSL `type` to hold behaviour or methods like an OOP class." } ], "module": "type-model", "name": "type", "prerequisites": [ "system" ], "worked_examples": [ { "citation": "magatama/vsl/year10-demonstrator-seed.varro#L126", "explanation": "A `type` names a record. Each `field` has a name, a kind (string, uri, integer, bool, a named enum, or an array like string[]), and a required/optional marker.", "snippet": "type ImportedArtefact {\n field artefact_id: string required\n field source_ref: uri required\n field cannot_authorise: string[] required\n}" }, { "citation": "magatama/vsl/year10-demonstrator-seed.varro#L144", "explanation": "Fields can be constrained to a declared enum. Here the trailing comment names the enum that backs the field, moving a closed value set from prose into the type system.", "snippet": "type RustComponentBoundary {\n field component_role: string required # component-role\n field permitted_output_authority: string required # output-authority\n}" } ] }, { "checks": [ { "answer": "It constrains the schema: an instance of the enclosing type is invalid if the field is absent. Enforcement is at parse/validation of the VSL, not at runtime — `optional` would admit absence. The kind (`uri`) separately constrains the value's shape.", "prompt": "In `field source_pdf_ref: uri required`, what does the `required` keyword constrain, and at what layer is it enforced?" } ], "citations": [ "mentormind-program/experiments/goals-experiment/bootstrap/glossary.md", "mentormind-program/experiments/goals-experiment/bootstrap/glossary.md#L19", "mentormind-program/experiments/hsc-exam-parser/spec/parser.varro#L113" ], "definition": "A typed member of a type: name: type [required|optional].", "id": "concept:construct--field", "misconceptions": [ { "citation": "mentormind-program/experiments/goals-experiment/bootstrap/glossary.md#L19", "correction": "`optional` only declares that absence is admissible; it supplies no value and no default. There is no inferred zero. A consumer must treat an optional field as possibly-absent, not as present-with-default. Required/optional is a presence obligation in the type, distinct from any value semantics.", "wrong_belief": "Coming from SQL/ORM or Rust structs, a senior engineer reads `optional` as \"nullable, defaults to NULL/zero\" and assumes the system fills a value when the field is absent." } ], "module": "type-model", "name": "field", "prerequisites": [ "type" ], "worked_examples": [ { "citation": "mentormind-program/experiments/hsc-exam-parser/spec/parser.varro#L113", "explanation": "A field is `field : ` inside a `type` block. The obligation is part of the type, not a downstream runtime check: `required` means the parser rejects an instance missing the member; `optional` admits absence. Kinds are the closed set string/markdown/uri/integer/number/bool, arrays (`string[]`), and named enums. Unlike a struct field default in Rust, optionality here is a declared property of the schema, not a `Default` impl — there is no inferred zero value, absence is absence.", "snippet": "type SourcePaper {\n field paper_id: string required\n field total_marks: integer required\n field structure_evidence_ref: uri optional\n}" }, { "citation": "mentormind-program/experiments/goals-experiment/bootstrap/glossary.md#L19", "explanation": "Typing a field by a named enum closes its value set at the schema layer: `subject` can only be `physics` or `chemistry`, and an unlisted value fails validation before any code runs. This is the VSL idiom for lifting a prose constraint (\"subject is one of...\") into a checkable invariant. Evaluate it against a stringly-typed alternative (`field subject: string`): the enum form makes the illegal state unrepresentable in the spec, which is precisely the property you would otherwise have to defend with a hand-written validator and a test.", "snippet": "enum Subject { physics chemistry }\ntype SourcePaper {\n field subject: Subject required\n}" } ] }, { "checks": [ { "answer": "No. An `enum` is a closed set of `value` variants; the checker rejects any undeclared value. That closedness moves constraints from prose into the type system.", "prompt": "Can a field typed by an enum hold a value not declared in that enum?" } ], "citations": [ "magatama/vsl/year10-demonstrator-seed.varro#L37", "magatama/vsl/year10-demonstrator-seed.varro#L79", "mentormind-program/experiments/goals-experiment/bootstrap/glossary.md", "mentormind-program/experiments/goals-experiment/bootstrap/glossary.md#L22" ], "definition": "A closed set of named variant values.", "id": "concept:construct--enum", "misconceptions": [ { "citation": "mentormind-program/experiments/goals-experiment/bootstrap/glossary.md#L22", "correction": "An `enum` is a closed set. A field typed by it can hold only the declared `value` variants; the checker rejects anything else. That closedness is the point.", "wrong_belief": "Learners think a field can carry an enum value that was not declared, treating the enum as a hint." } ], "module": "type-model", "name": "enum", "prerequisites": [ "field", "type" ], "worked_examples": [ { "citation": "magatama/vsl/year10-demonstrator-seed.varro#L79", "explanation": "An `enum` declares a finite set of `value` variants. A field typed by this enum can only ever hold one of these names, so illegal states become unrepresentable.", "snippet": "enum output-authority {\n value student-analysis\n value teacher-controlled-model\n value vendor-only\n value blocked\n}" }, { "citation": "magatama/vsl/year10-demonstrator-seed.varro#L37", "explanation": "Using a free `string` lets any typo through. Declaring an `enum` and naming it on the field documents the legal set and lets the checker reject unknown variants.", "snippet": "# weak: field stage: string\n# strong: enum demonstrator-import-stage { value source-of-truth-check ... }\n# field imported_stage: string required # demonstrator-import-stage" } ] }, { "checks": [ { "answer": "A risk class and a `lowers-to` target, and it runs under preview-by-default. There is no ungoverned action; it is invoked by the `run` verb.", "prompt": "What does an `action` declaration carry beyond its inputs?" } ], "citations": [ "mentormind-program/experiments/goals-experiment/bootstrap/glossary.md", "mentormind-program/experiments/goals-experiment/bootstrap/glossary.md#L24", "mentormind-program/experiments/hsc-exam-parser/spec/parser.varro#L395" ], "definition": "A governed, risk-typed operation with declared inputs.", "id": "concept:construct--action", "misconceptions": [ { "citation": "mentormind-program/experiments/goals-experiment/bootstrap/glossary.md#L24", "correction": "An `action` is risk-typed and governed: it declares inputs, a risk class, and a lowers-to target, and it runs under preview-by-default. There is no ungoverned action.", "wrong_belief": "Learners assume an `action` just executes code with no risk gating." } ], "module": "behaviour", "name": "action", "prerequisites": [ "enum", "type" ], "worked_examples": [ { "citation": "mentormind-program/experiments/goals-experiment/bootstrap/glossary.md#L24", "explanation": "An `action` declares a governed operation: its typed inputs, a risk class, and a `lowers-to` target. It is invoked by the `run` verb and is subject to preview-by-default.", "snippet": "action authorize-ignition {\n input authorization_lane: string required\n risk high\n lowers-to \"helios://action/authorize-ignition\"\n}" }, { "citation": "mentormind-program/experiments/hsc-exam-parser/spec/parser.varro#L395", "explanation": "An `action` is a governed mutation contract with four parts: a `risk` class, a `binding` (whether a concrete lowering target is required), and typed `input`s. The action does not contain an implementation body — it declares the contract and `lowers-to` an executable target downstream. Evaluate the separation: the risk class and binding are reviewable governance metadata sitting in front of the code, so an approver reasons about blast radius from the contract alone, before any implementation exists.", "snippet": "action parse-paper {\n risk low\n binding required\n input source_paper_ref: uri required\n input parser_kg_ref: uri required\n}" } ] }, { "checks": [ { "answer": "Yes, top to bottom. Order matters because steps depend on earlier ones; a `check` before a `create` blocks the create when the check fails.", "prompt": "Do the steps of a `workflow` run in order, and why does it matter?" } ], "citations": [ "edu/varro/edukg/kg/overlay/assessments-entities.ndjson", "magatama/vsl/year10-demonstrator-seed.varro#L203", "mentormind-program/experiments/goals-experiment/bootstrap/glossary.md", "mentormind-program/experiments/goals-experiment/bootstrap/glossary.md#L26", "mentormind-program/experiments/hsc-exam-parser/spec/parser.varro#L409" ], "definition": "An ordered sequence of steps composing actions/queries.", "id": "concept:construct--workflow", "misconceptions": [ { "citation": "mentormind-program/experiments/goals-experiment/bootstrap/glossary.md#L26", "correction": "A `workflow` is an ordered sequence. Steps run top to bottom; a `check` placed before a `create` exists precisely so the create cannot run if the check fails.", "wrong_belief": "Learners think workflow steps are an unordered set that may run in parallel." } ], "module": "behaviour", "name": "workflow", "prerequisites": [ "action", "ask" ], "worked_examples": [ { "citation": "magatama/vsl/year10-demonstrator-seed.varro#L203", "explanation": "A `workflow` composes the five verbs into an ordered behaviour. Read top to bottom: gather, present, validate, then create. Order matters because each step can depend on the last.", "snippet": "workflow classify-year10-evidence {\n ask imported-artefact\n show allowed-claims\n check evidence-class\n create evidence-class-mapping\n}" }, { "citation": "mentormind-program/experiments/hsc-exam-parser/spec/parser.varro#L409", "explanation": "A `workflow` is a staged behaviour sequence written as verb + target pairs (`inspect`, `resolve`, `check`, `render`, `emit`...). It composes the declared queries and actions into an ordered pipeline; the ordering is the contract. Note these stage verbs are workflow-internal and distinct from the five-verb command grammar (`ask/show/check/run/create`) at the conversation surface. Evaluate it as a declarative DAG-of-steps: the spec states the sequence and bindings, and lowering generates the executor, so reordering is a spec edit, not a code refactor.", "snippet": "workflow parse-paper-pipeline {\n inspect selection\n resolve parser-knowledge\n resolve source-paper\n check validate-parser-spec\n render center.detail\n emit route gate.round_trip\n}" } ] }, { "checks": [ { "answer": "No. A query is a read contract: it declares output + authority and is non-mutating by construction. Mutation is the province of `action` (risk-typed, bound). The grammar makes the read/write distinction structural, so a query cannot carry a risk class.", "prompt": "A `query` declares an output type and an authority. Can it also declare a risk class and mutate state? Why or why not?" } ], "citations": [ "helios-projects/project/knowledge-graphs/tools/varro-protocol/src/vsl.rs", "mentormind-program/experiments/goals-experiment/bootstrap/glossary.md", "mentormind-program/experiments/goals-experiment/bootstrap/glossary.md#L28", "mentormind-program/experiments/hsc-exam-parser/spec/parser.varro#L402" ], "definition": "A read of state with declared output and authorities.", "id": "concept:construct--query", "misconceptions": [ { "citation": "mentormind-program/experiments/goals-experiment/bootstrap/glossary.md#L28", "correction": "In VSL the read/write split is in the grammar: a `query` declares only output + authority and is non-mutating; anything that changes state is an `action` with a declared risk class and binding. The category boundary is enforced by the parser, not by convention.", "wrong_belief": "Because SQL `query` can call functions with side effects and a GraphQL field resolver can mutate, an engineer assumes a VSL `query` is just \"any callable\" and may write." } ], "module": "behaviour", "name": "query", "prerequisites": [ "workflow" ], "worked_examples": [ { "citation": "mentormind-program/experiments/goals-experiment/bootstrap/glossary.md#L28", "explanation": "A `query` in VSL is a named read contract: it declares an `output` type (here a `ParsedPaper[]`) and the `authority` it reads from. It never mutates. The declared output is part of the contract surface, so an agent can statically know the shape of what a query returns without executing it. Contrast the `ask`/`show` verbs of the five-verb command grammar: those are interactive read commands at the conversation surface, whereas a `query` is a reusable declared contract inside a `system`.", "snippet": "query parsed-papers {\n output ParsedPaper[]\n authority knowledge-graph\n}" }, { "citation": "mentormind-program/experiments/hsc-exam-parser/spec/parser.varro#L402", "explanation": "Place a `query` and an `action` side by side: the query has only an `output` and an `authority` and carries no `risk` because it cannot change state; the action carries a `risk` class and a `binding` precisely because it can. Evaluate the design: putting the mutate/read split into the grammar (queries simply cannot declare a risk class) means a reviewer never has to audit a query for side effects — the absence of a risk field is a proof obligation discharged by parsing, not by reading the body.", "snippet": "query open-gates { output GateStatus[] authority knowledge-graph }\naction run-round-trip-gate {\n risk none\n binding required\n input parsed_paper_ref: uri required\n}" } ] }, { "checks": [ { "answer": "`varro` is a member of the closed set of lowering targets (alongside `helios.contracts.context-bundle`). It names the typed downstream artifact channel the lowering pass must emit, not an output file path. `-> binary` fails because `binary` is not a recognised compile target — it is a spec-level error caught at compile/validation, not a missing output at build time.", "prompt": "In `compile workspace-runtime -> varro`, what is `varro`, and what fails if you write `compile workspace-runtime -> binary`?" } ], "citations": [ "helios-projects/project/knowledge-graphs/tools/varro-protocol/src/vsl.rs#L294", "mentormind-program/experiments/goals-experiment/bootstrap/glossary.md", "mentormind-program/experiments/goals-experiment/spec/varro-v1-product-spec.varro#L156" ], "definition": "A lowering target: compile -> .", "id": "concept:construct--compile", "misconceptions": [ { "citation": "helios-projects/project/knowledge-graphs/tools/varro-protocol/src/vsl.rs#L294", "correction": "`compile -> ` declares a lowering *obligation* against a closed set of typed targets (`varro`, `helios.contracts.context-bundle`); it does not produce a machine binary. The compiler's product is a lowering plan plus contract artifacts (compiled-contracts.json, lowering-plan.json, binding-report.json) — typed JSON the platform consumes, not executable code. The unit is a named lowering channel, not a build output path.", "wrong_belief": "A senior engineer reads `compile` as the familiar source -> object -> binary pipeline and expects the target to be an output file/format (an ELF, a wasm blob, a tarball)." } ], "module": "surfaces", "name": "compile", "prerequisites": [ "Crystal" ], "worked_examples": [ { "citation": "mentormind-program/experiments/goals-experiment/spec/varro-v1-product-spec.varro#L156", "explanation": "A `compile` line is `compile -> ` 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.", "snippet": "compile workspace-runtime -> varro\ncompile browser-contract -> helios.contracts.context-bundle" }, { "citation": "helios-projects/project/knowledge-graphs/tools/varro-protocol/src/vsl.rs#L294", "explanation": "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.", "snippet": "compile workspace-runtime -> varro\ncompile browser-contract -> helios.contracts.context-bundle" } ] }, { "checks": [ { "answer": "The value must be a canonical `helios://` URI — validation checks `uri.starts_with(\"helios://\")`. A route value that does not start with `helios://` is rejected at validation with a diagnostic (`route ... must use a canonical helios:// URI`). The name on the left is just a stable handle; the constraint lives on the address.", "prompt": "In `route public.do = \"...\"`, what is the validation rule on the right-hand side, and what is the consequence of violating it?" } ], "citations": [ "edu/varro/edukg/kg/overlay/assessments-entities.ndjson", "helios-projects/project/intelligent-processes/specification-crystalisation/specs/arch-model/uri.varro#L26", "helios-projects/project/knowledge-graphs/tools/varro-protocol/src/vsl.rs#L2178", "helios-projects/project/knowledge-graphs/tools/varro-protocol/src/vsl.rs#L370", "mentormind-program/experiments/goals-experiment/bootstrap/glossary.md", "mentormind-program/experiments/goals-experiment/spec/varro-v1-product-spec.varro#L159", "mentormind-program/experiments/goals-experiment/spec/varro-v1-product-spec.varro#L160" ], "definition": "A named helios:// resource address.", "id": "concept:type--helios-arch-uri--route", "misconceptions": [ { "citation": "helios-projects/project/knowledge-graphs/tools/varro-protocol/src/vsl.rs#L370", "correction": "A VSL route is `route = \"\"` — a named, validated address into the Helios resource space, resolved by the platform through the authority stack, with no HTTP method and no handler. It is closer to a typed symlink or a registered resource identifier than to a web route. The query string selects a view/tab/bind mode, not query parameters your code parses.", "wrong_belief": "Coming from axum/Express, an engineer reads `route` as a request-path-to-handler mapping (`GET /public/do -> handler`) and expects a method, params, and a response body served by application code." } ], "module": "surfaces", "name": "route", "prerequisites": [ "compile" ], "worked_examples": [ { "citation": "mentormind-program/experiments/goals-experiment/spec/varro-v1-product-spec.varro#L159", "explanation": "A `route` is `route = \"\"`, 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.", "snippet": "route spec.contract = \"helios://local/mentormind/goals-experiment/spec/varro-v1-product-spec?view=detail&tab=contract&bind=auto\"" }, { "citation": "mentormind-program/experiments/goals-experiment/spec/varro-v1-product-spec.varro#L160", "explanation": "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.", "snippet": "route spec.instance = \"helios://local/mentormind/goals-experiment/spec/varro-v1-learner-site-instance?view=detail&tab=state&bind=auto\"\nroute public.read = \"helios://external/mentormind/varro-v1/public/read?view=detail&tab=live&bind=auto\"" } ] }, { "checks": [ { "answer": "Three operands: the name `spec.detail` (a handle for the binding); the context selector `doc:varro-v1-*` after `for` (which resources this applies to — a glob over doc ids); and the target `center.detail` after `uses` (the render surface to present matches with). The grammar is `view for uses `; parse fails if `for` or `uses` is missing.", "prompt": "Decompose `view spec.detail for doc:varro-v1-* uses center.detail` into its named parts and say what each one binds." } ], "citations": [ "helios-projects/project/knowledge-graphs/tools/varro-protocol/src/vsl.rs#L378", "helios-projects/project/knowledge-graphs/tools/varro-protocol/src/vsl.rs#L3785", "mentormind-program/experiments/goals-experiment/bootstrap/glossary.md", "mentormind-program/experiments/goals-experiment/spec/varro-v1-product-spec.varro#L168", "mentormind-program/experiments/goals-experiment/spec/varro-v1-product-spec.varro#L169" ], "definition": "A render binding for a doc/query selection.", "id": "concept:construct--view", "misconceptions": [ { "citation": "helios-projects/project/knowledge-graphs/tools/varro-protocol/src/vsl.rs#L378", "correction": "A VSL view is `view for uses ` — a binding that says which render surface a *class of already-resolved resources* is presented through. It computes no data (unlike a SQL view) and contains no markup or props (unlike a component). It is a declarative entry in the render-layer dispatch table; the platform applies it, the spec only states the mapping.", "wrong_belief": "An engineer reads `view` as either a materialised/virtual SQL view (a stored query returning rows) or a UI component (markup + props), and expects it to either produce data or render DOM." } ], "module": "surfaces", "name": "view", "prerequisites": [ "route" ], "worked_examples": [ { "citation": "mentormind-program/experiments/goals-experiment/spec/varro-v1-product-spec.varro#L168", "explanation": "A `view` is `view for uses `, 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.", "snippet": "view spec.detail for doc:varro-v1-* uses center.detail" }, { "citation": "mentormind-program/experiments/goals-experiment/spec/varro-v1-product-spec.varro#L169", "explanation": "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.", "snippet": "view spec.detail for doc:varro-v1-* uses center.detail\nview spec.table for query:varro-v1-* uses center.table" } ] }, { "checks": [ { "answer": "`default` is from the closed kind enum `{default, alternate}`; any other token is rejected as `invalid_agent_kind`. The `->` binds the selected context (`doc:varro-v1-*`, after `for`) to a profile id on the right (`agent:software.architect`). The grammar is `agent for -> `.", "prompt": "In `agent default for doc:varro-v1-* -> agent:software.architect`, which token set is `default` drawn from, and what does the `->` bind to?" } ], "citations": [ "helios-projects/project/knowledge-graphs/tools/varro-protocol/src/vsl.rs#L3802", "helios-projects/project/knowledge-graphs/tools/varro-protocol/src/vsl.rs#L394", "mentormind-program/experiments/goals-experiment/bootstrap/glossary.md", "mentormind-program/experiments/goals-experiment/spec/varro-v1-product-spec.varro#L171", "mentormind-program/experiments/goals-experiment/spec/varro-v1-product-spec.varro#L172" ], "definition": "An agent binding for a doc/selection.", "id": "concept:construct--agent", "misconceptions": [ { "citation": "helios-projects/project/knowledge-graphs/tools/varro-protocol/src/vsl.rs#L394", "correction": "`agent for -> ` is a declarative binding: it registers which agent profile the platform attaches when a matching resource is acted on. Loading the spec spawns nothing. It is role-keyed dependency injection (`default` vs `alternate`), resolved on demand by the host, not a daemon, cron, or event loop.", "wrong_belief": "An engineer reads `agent default for ... -> ...` as launching a long-running process or background worker that polls the selection and acts autonomously once the spec loads." } ], "module": "surfaces", "name": "agent", "prerequisites": [ "view" ], "worked_examples": [ { "citation": "mentormind-program/experiments/goals-experiment/spec/varro-v1-product-spec.varro#L171", "explanation": "An `agent` line is `agent for -> `, 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.", "snippet": "agent default for doc:varro-v1-* -> agent:software.architect" }, { "citation": "mentormind-program/experiments/goals-experiment/spec/varro-v1-product-spec.varro#L172", "explanation": "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.", "snippet": "agent default for doc:varro-v1-* -> agent:software.architect\nagent alternate for doc:varro-v1-* -> agent:factory.independent-judge" } ] }, { "checks": [ { "answer": "It is required: the validator reports `system is missing context root = ...` and the spec fails. The binding establishes the system's canonical resolution root in the Helios resource space — the absolute helios:// address (with default view/tab/bind) that routes and views are interpreted relative to when the system is opened.", "prompt": "What happens if a `system` block omits `context root = ...`, and what does that binding establish?" } ], "citations": [ "helios-projects/project/knowledge-graphs/tools/varro-protocol/src/vsl.rs#L1960", "helios-projects/project/knowledge-graphs/tools/varro-protocol/src/vsl.rs#L243", "mentormind-program/experiments/goals-experiment/bootstrap/glossary.md", "mentormind-program/experiments/goals-experiment/spec/varro-v1-product-spec.varro#L14" ], "definition": "A context root binding for a system.", "id": "concept:construct--context", "misconceptions": [ { "citation": "helios-projects/project/knowledge-graphs/tools/varro-protocol/src/vsl.rs#L243", "correction": "VSL `context root = \"\"` is a single, required, *static* binding: the system's canonical anchor address in the resource space. It is not a value passed down a call/render tree and there is no provider/consumer override hierarchy. Think absolute base href for the system, not dynamic scope.", "wrong_belief": "An engineer reads `context` as React Context / a thread-local / ambient request scope — a dynamically-scoped value implicitly threaded through callees and overridable per subtree." } ], "module": "surfaces", "name": "context", "prerequisites": [ "agent" ], "worked_examples": [ { "citation": "mentormind-program/experiments/goals-experiment/spec/varro-v1-product-spec.varro#L14", "explanation": "`context root = \"\"` 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.", "snippet": "context root = \"helios://local/mentormind/goals-experiment/spec/varro-v1-product-spec?view=detail&tab=contract&bind=auto\"" }, { "citation": "helios-projects/project/knowledge-graphs/tools/varro-protocol/src/vsl.rs#L1960", "explanation": "The validator emits `system 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.", "snippet": "system mentormind.product.varro_v1 {\n mission \"...\"\n authority lane \"operator:research\"\n context root = \"helios://local/mentormind/goals-experiment/spec/varro-v1-product-spec?view=detail&tab=contract&bind=auto\"\n}" } ] }, { "checks": [ { "answer": "`commit-mode` is a runtime setting (key/value) read by the lowering pass via `runtime_setting(runtime, \"commit-mode\")`. `host-only` establishes that only the host may commit mutations — callers may describe and review an action but cannot apply it themselves. This is the runtime-layer expression of preview-by-default: `--execute`/commit authority rests with the host.", "prompt": "In `runtime specification { host governed; commit-mode host-only }`, what is `commit-mode` and what governance property does `host-only` establish?" } ], "citations": [ "helios-projects/project/knowledge-graphs/tools/varro-protocol/src/vsl.rs#L2346", "helios-projects/project/knowledge-graphs/tools/varro-protocol/src/vsl.rs#L457", "mentormind-program/experiments/goals-experiment/bootstrap/glossary.md", "mentormind-program/experiments/goals-experiment/spec/varro-v1-product-spec.varro#L200" ], "definition": "The runtime specification block (host, commit-mode).", "id": "concept:construct--runtime", "misconceptions": [ { "citation": "helios-projects/project/knowledge-graphs/tools/varro-protocol/src/vsl.rs#L457", "correction": "A VSL `runtime { ... }` block is a typed settings bag (key/value pairs like `host governed`, `commit-mode host-only`) that declares the system's authority and commit posture for the lowering pass to read. It boots nothing and runs no code; it is a governance manifest. Defaults apply for absent keys (`host` defaults to `governed`).", "wrong_belief": "An engineer reads `runtime` as a language runtime, VM, or process supervisor (Node, JVM, Wasmtime) that the block configures and starts when the spec loads." } ], "module": "surfaces", "name": "runtime", "prerequisites": [ "context" ], "worked_examples": [ { "citation": "mentormind-program/experiments/goals-experiment/spec/varro-v1-product-spec.varro#L200", "explanation": "A `runtime { ... }` 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.", "snippet": "runtime specification {\n host governed\n commit-mode host-only\n}" }, { "citation": "helios-projects/project/knowledge-graphs/tools/varro-protocol/src/vsl.rs#L2346", "explanation": "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.", "snippet": "runtime specification {\n host governed\n commit-mode host-only\n}" } ] }, { "checks": [ { "answer": "draft, checked, bound, hardened. At `bound` the spec is tied to a concrete contract, so unresolved references become checker errors rather than warnings.", "prompt": "List the four VSL maturity rungs in order and say what changes at `bound`." }, { "answer": "`draft` tolerates unresolved references and inferred defaults; it represents unverified intent so authoring can proceed before everything is bound.", "prompt": "What does the `draft` maturity rung allow that stricter rungs do not?" } ], "citations": [ "helios-projects/project/knowledge-graphs/tools/varro-protocol/src/vsl.rs", "helios-projects/project/knowledge-graphs/tools/varro-protocol/src/vsl.rs#L224", "helios-projects/project/knowledge-graphs/tools/varro-protocol/src/vsl.rs#L225", "magatama/vsl/year10-demonstrator-seed.varro#L18", "mentormind-program/experiments/goals-experiment/bootstrap/glossary.md#L29" ], "definition": "VslMaturity level: unverified intent.", "id": "concept:maturity--draft", "misconceptions": [ { "citation": "mentormind-program/experiments/goals-experiment/bootstrap/glossary.md#L29", "correction": "`draft` is a legitimate rung for in-progress intent; it deliberately tolerates unresolved refs and inferred defaults. It is the start of the ladder draft to checked to bound to hardened, not a failure.", "wrong_belief": "Learners read `maturity draft` as a defect or an unfinished mistake." } ], "module": "maturity", "name": "draft", "prerequisites": [ "query" ], "worked_examples": [ { "citation": "magatama/vsl/year10-demonstrator-seed.varro#L18", "explanation": "`maturity draft` is the lowest rung: unverified intent. At draft the checker tolerates unresolved references and inferred defaults so authoring can proceed before everything is bound.", "snippet": "system magatama.seed.year10_demonstrator {\n maturity draft\n}" }, { "citation": "helios-projects/project/knowledge-graphs/tools/varro-protocol/src/vsl.rs#L225", "explanation": "`maturity draft` is the lowest rung of the ladder `draft -> checked -> bound -> hardened`. At draft, unresolved references and inferred defaults are tolerated, and lowering diagnostics are warnings rather than errors. This corresponds to `VslMaturity::Draft`, which the lowering severity function maps to `Warning`. Evaluate it as a TODO-tolerant compile mode: the document parses and is queryable while still incomplete, so you can stand up structure before every reference resolves.", "snippet": "system parser-spec {\n maturity draft\n # refs may dangle; defaults may be inferred at this rung\n}" } ] }, { "checks": [ { "answer": "It guarantees the checker passed (refs resolve, types consistent). It does not mean bound to a concrete contract or hardened for production.", "prompt": "What does the `checked` rung guarantee, and what does it not?" } ], "citations": [ "edu/varro/edukg/kg/overlay/assessments-entities.ndjson", "helios-projects/project/knowledge-graphs/tools/varro-protocol/src/vsl.rs", "helios-projects/project/knowledge-graphs/tools/varro-protocol/src/vsl.rs#L226" ], "definition": "VslMaturity level: validated by the checker.", "id": "concept:maturity--checked", "misconceptions": [ { "citation": "helios-projects/project/knowledge-graphs/tools/varro-protocol/src/vsl.rs#L226", "correction": "`checked` only means the checker passed. Two rungs remain: `bound` (tied to a concrete contract) and `hardened` (production, strictest diagnostics).", "wrong_belief": "Learners think once a spec is `checked` it is production-ready." } ], "module": "maturity", "name": "checked", "prerequisites": [ "draft" ], "worked_examples": [ { "citation": "helios-projects/project/knowledge-graphs/tools/varro-protocol/src/vsl.rs#L226", "explanation": "`checked` is the second rung: the document has passed the checker. References resolve and types are consistent, but it is not yet bound to a concrete contract or hardened for production.", "snippet": "maturity checked" }, { "citation": "helios-projects/project/knowledge-graphs/tools/varro-protocol/src/vsl.rs#L226", "explanation": "`maturity checked` is the second rung. Structure is parser-validated (`varro check vsl` passes) but lowering diagnostics remain warnings — like `Draft`, `VslMaturity::Checked` maps to `Warning` in the lowering severity function. The jump in obligation happens at `bound`, not here. Evaluate the boundary: checked guarantees the shape is well-formed and queryable, but does not yet force every reference to resolve into an executable lowering — that promise belongs to the next rung.", "snippet": "system parser-spec {\n maturity checked\n # structure parser-validated; lowering diagnostics still warnings\n}" } ] }, { "checks": [ { "answer": "At `bound` the spec is bound to a concrete contract, so unresolved references are errors. It is stricter than `checked` but below `hardened`.", "prompt": "What is true at the `bound` rung that is not true at `checked`?" } ], "citations": [ "helios-projects/project/knowledge-graphs/tools/varro-protocol/src/vsl.rs", "helios-projects/project/knowledge-graphs/tools/varro-protocol/src/vsl.rs#L227" ], "definition": "VslMaturity level: bound to a concrete contract.", "id": "concept:maturity--bound", "misconceptions": [ { "citation": "helios-projects/project/knowledge-graphs/tools/varro-protocol/src/vsl.rs#L227", "correction": "`bound` ties the spec to a concrete contract so unresolved refs become errors, but `hardened` is a further rung that applies the strictest production posture. Bound is necessary but not the summit.", "wrong_belief": "Learners conflate `bound` with the top production rung." } ], "module": "maturity", "name": "bound", "prerequisites": [ "checked" ], "worked_examples": [ { "citation": "helios-projects/project/knowledge-graphs/tools/varro-protocol/src/vsl.rs#L227", "explanation": "`bound` is the third rung: the spec is bound to a concrete contract, so unresolved references become checker errors rather than warnings. Promotion to bound is the point at which laxness ends.", "snippet": "maturity bound" }, { "citation": "helios-projects/project/knowledge-graphs/tools/varro-protocol/src/vsl.rs#L227", "explanation": "`maturity bound` is the third rung and the first with teeth: the lowering severity function escalates `VslMaturity::Bound` (and `Hardened`) to `Error`, so a missing or unresolved lowering target now fails rather than warns. This is the rung where the spec commits to being executable. Evaluate it as flipping `-Werror` on for lowering: everything that was a tolerable gap at draft/checked now blocks promotion.", "snippet": "system parser-spec {\n maturity bound\n # lowering diagnostics now ERROR, not warning\n}" } ] }, { "checks": [ { "answer": "The top, production rung: everything is bound and checked, the strictest diagnostics apply. It should not be silently relaxed back to draft.", "prompt": "What does the `hardened` maturity rung represent?" } ], "citations": [ "helios-projects/project/intelligent-processes/specification-crystalisation/specification-crystallisation-architecture-v3.md", "helios-projects/project/knowledge-graphs/tools/varro-protocol/src/vsl.rs", "helios-projects/project/knowledge-graphs/tools/varro-protocol/src/vsl.rs#L228" ], "definition": "VslMaturity level: hardened/production.", "id": "concept:maturity--hardened", "misconceptions": [ { "citation": "helios-projects/project/knowledge-graphs/tools/varro-protocol/src/vsl.rs#L228", "correction": "`hardened` is the strictest, production rung, but it can still be revised through governed change. What it should not be is silently relaxed back to draft to dodge diagnostics.", "wrong_belief": "Learners think a `hardened` spec is frozen and cannot be revised." } ], "module": "maturity", "name": "hardened", "prerequisites": [ "bound" ], "worked_examples": [ { "citation": "helios-projects/project/knowledge-graphs/tools/varro-protocol/src/vsl.rs#L228", "explanation": "`hardened` is the top rung: production-ready. Everything is bound, checked, and the strictest diagnostics apply. A hardened system should not be silently relaxed back to draft.", "snippet": "maturity hardened" }, { "citation": "helios-projects/project/knowledge-graphs/tools/varro-protocol/src/vsl.rs#L228", "explanation": "`maturity hardened` is the top rung of the ladder. Like `bound`, `VslMaturity::Hardened` maps lowering diagnostics to `Error`; hardened is the strictest promotion state a `.varro` document declares. This maturity ladder is the document's own rung and is orthogonal to the plasma->crystal phase model: maturity is the VSL's self-declared strictness, while phase describes how far the spec has crystallised toward proved Rust. Evaluate the design: a document can be `hardened` VSL and still only sit at the Gas phase, because the two axes measure different commitments.", "snippet": "system parser-spec {\n maturity hardened\n # top of draft mathematical certainty" } ] }, { "checks": [ { "answer": "It previews: it describes the intended governed action and its review/authority posture and commits nothing. The mutation occurs only if you re-issue with `--execute`. The safe (preview) path is the default; execution is opt-in.", "prompt": "You issue `varro create thing x` with no extra flags. What does the system do, and what flag changes that?" } ], "citations": [ "edu/varro/edukg/kg/overlay/assessments-entities.ndjson", "mentormind-program/experiments/goals-experiment/bootstrap/glossary.md", "mentormind-program/experiments/goals-experiment/bootstrap/glossary.md#L12", "mentormind-program/experiments/goals-experiment/bootstrap/glossary.md#L31" ], "definition": "Default-safe principle: actions preview before they commit.", "id": "concept:principle--preview-by-default", "misconceptions": [ { "citation": "mentormind-program/experiments/goals-experiment/bootstrap/glossary.md#L31", "correction": "The polarity is reversed. Preview is the default; mutation is the opt-in (`--execute`). You cannot accidentally mutate by forgetting a flag — forgetting a flag yields a preview. This is what makes the surface safe for autonomous agents.", "wrong_belief": "An engineer maps preview-by-default onto the familiar `--dry-run` pattern: the command runs for real unless you opt into a dry run." } ], "module": "governance", "name": "preview-by-default", "prerequisites": [ "Authority Stack" ], "worked_examples": [ { "citation": "mentormind-program/experiments/goals-experiment/bootstrap/glossary.md#L31", "explanation": "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.", "snippet": "$ varro run parse-paper --source paper.pdf\n# PREVIEW: action parse-paper (risk low, binding required)\n# authority: agent:helios.demonstrator-import\n# would write: parsed_paper, round_trip_input\n# re-run with --execute to commit\n$ varro run parse-paper --source paper.pdf --execute" }, { "citation": "mentormind-program/experiments/goals-experiment/bootstrap/glossary.md#L12", "explanation": "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.", "snippet": "varro ask system status # read, runs directly\nvarro show gate.round_trip # read, runs directly\nvarro create demonstrator x # mutate -> previews first" } ] }, { "checks": [ { "answer": "The source wins; Varro is wrong by definition. Varro is only a window (layer 2) over authoritative sources (layer 1). State of record lives in the sources, so Varro holds no independent truth and can be rebuilt without data loss.", "prompt": "Varro reports one value; the underlying Rust model reports another. Per the Authority Stack, which is authoritative, and what does that imply about where state of record lives?" } ], "citations": [ "magatama/vsl/year10-demonstrator-seed.varro#L11", "mentormind-program/experiments/goals-experiment/bootstrap/glossary.md", "mentormind-program/experiments/goals-experiment/bootstrap/glossary.md#L9" ], "definition": "The layered authority model governing who may do what.", "id": "concept:gov--authority-stack", "misconceptions": [ { "citation": "mentormind-program/experiments/goals-experiment/bootstrap/glossary.md#L9", "correction": "Varro is the window (layer 2), never the source (layer 1). The Rust model, governance contract, policy engine, and knowledge graph are authoritative; if Varro disagrees with them, Varro is wrong. Varro caches and presents truth, it does not own it.", "wrong_belief": "An engineer treats Varro like an application server that owns the database and is the authority — \"ask Varro and trust the answer.\"" } ], "module": "governance", "name": "Authority Stack", "prerequisites": [ "runtime" ], "worked_examples": [ { "citation": "mentormind-program/experiments/goals-experiment/bootstrap/glossary.md#L9", "explanation": "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.\"", "snippet": "# layer 1 (authoritative sources): Rust model, governance contract,\n# policy engine, knowledge graph\n# layer 2 (the window): Varro\n# layer 3 (callers): humans, agents\n# invariant: if Varro and a source disagree, Varro is wrong." }, { "citation": "magatama/vsl/year10-demonstrator-seed.varro#L11", "explanation": "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.", "snippet": "authority lane \"operator:magatama-program\"\nauthority lane \"agent:helios.demonstrator-import\"\nauthority lane \"reviewer:school-whs\"" } ] }, { "checks": [ { "answer": "VSL is the declarative specification language for describing systems, types, views, workflows, and bootstrap descriptors — it produces a typed, checkable, lowerable spec. The five-verb grammar is the interaction grammar for driving Varro at the surface (asking, showing, checking, running, creating), where unknown verbs are rejected. They are distinct layers: VSL authors the contracts; the five verbs operate the window over them.", "prompt": "VSL and the five-verb grammar (`ask`, `show`, `check`, `run`, `create`) are both 'Varro languages'. What does each do, and why are they distinct?" } ], "citations": [ "helios-projects/project/intelligent-processes/specification-crystalisation/specification-crystallisation.varro#L64", "helios-projects/project/knowledge-graphs/tools/varro-protocol/src/vsl.rs#L224", "mentormind-program/experiments/goals-experiment/bootstrap/glossary.md", "mentormind-program/experiments/goals-experiment/bootstrap/glossary.md#L14", "mentormind-program/experiments/goals-experiment/docs/load-bearing-specifications.md" ], "definition": "Varro Specification Language: the typed contract language.", "id": "concept:variant--helios-spec-crystallisation--phasemedium--vsl", "misconceptions": [ { "citation": "mentormind-program/experiments/goals-experiment/docs/load-bearing-specifications.md", "correction": "No. VSL makes the checkable STRUCTURE of a spec load-bearing; the Helios type system and Lean proofs (the Crystal phase) harden it further. But intent, rationale, DIAGRAMS, and worked EXAMPLES still belong in an AI spec - formalisation complements them, it does not remove them. VSL is one layer of the puzzle, not the whole of it.", "wrong_belief": "Typed VSL contracts replace prose, diagrams, and worked examples; a formal spec needs nothing else." }, { "citation": "mentormind-program/experiments/goals-experiment/bootstrap/glossary.md#L14", "correction": "VSL is a typed language with a parser, semantic analysis, a maturity ladder (`draft->checked->bound->hardened`), closed value sets (enums, compile targets), and validation rules (e.g. routes must be `helios://`, a system must declare `context root`). It lowers to contract artifacts. Config formats carry no enforced types, no maturity gating, and no lowering — VSL is a specification language, not a serialisation format.", "wrong_belief": "An engineer skims a .varro file and concludes it is a YAML/JSON-equivalent config format — structured key/value data with no semantics beyond what the consumer code chooses to read." } ], "module": "governance", "name": "VSL", "prerequisites": [ "preview-by-default" ], "worked_examples": [ { "citation": "mentormind-program/experiments/goals-experiment/bootstrap/glossary.md#L14", "explanation": "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.", "snippet": "system mentormind.product.varro_v1 {\n mission \"...\"\n authority lane \"operator:research\"\n domain education\n maturity draft\n compile workspace-runtime -> varro\n}" }, { "citation": "helios-projects/project/knowledge-graphs/tools/varro-protocol/src/vsl.rs#L224", "explanation": "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.", "snippet": "system mentormind.product.varro_v1 {\n maturity draft\n}" } ] }, { "checks": [ { "answer": "Three layers, top to bottom: authoritative sources (Rust model, governance contract, policy engine, knowledge graph) -> Varro (the window) -> callers. The rule is directional: if Varro and a source disagree, Varro is wrong. Varro holds no ground truth; it faithfully projects and governs over the authoritative layer.", "prompt": "In the Varro authority stack, what are the three layers and what is the rule when Varro and an authoritative source disagree?" } ], "citations": [ "mentormind-program/experiments/goals-experiment/bootstrap/glossary.md", "mentormind-program/experiments/goals-experiment/bootstrap/glossary.md#L31", "mentormind-program/experiments/goals-experiment/bootstrap/glossary.md#L9" ], "definition": "The specification system whose language is VSL.", "id": "concept:system--varro", "misconceptions": [ { "citation": "mentormind-program/experiments/goals-experiment/bootstrap/glossary.md#L9", "correction": "Varro is a governed query and control *window* over authoritative sources (Rust model, governance contract, policy engine, knowledge graph), not a store. It holds no ground truth: if Varro and a source disagree, Varro is wrong. It also previews mutations by default (commit-mode host-only; `--execute` opt-in), so it is a faithful read-through-and-govern facade, not a database or write-authoritative backend.", "wrong_belief": "An engineer treats Varro as the system of record — a backend or database that stores state, which callers read from and write to as the source of truth." } ], "module": "governance", "name": "Varro", "prerequisites": [ "VSL" ], "worked_examples": [ { "citation": "mentormind-program/experiments/goals-experiment/bootstrap/glossary.md#L9", "explanation": "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.", "snippet": "# authority stack\n# authoritative sources (Rust model, governance contract, policy engine, KG)\n# -> Varro (the window) -> callers\n# if Varro and a source disagree, Varro is wrong" }, { "citation": "mentormind-program/experiments/goals-experiment/bootstrap/glossary.md#L31", "explanation": "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.", "snippet": "# preview-by-default\n# Varro describes the intended governed action and its\n# review/authority posture BEFORE any mutation; --execute is opt-in" } ] } ], "distinct_sources": 11, "gate": "RICH + CITE enforced at E4 by kg-adequacy-edukg; every claim cites a resolvable real source", "generated_for": "audience:ai-agent", "modules": [ { "blurb": "The closed command grammar: ask, show, check, run, create.", "code": "01", "concepts": [ "ask", "show", "check", "run", "create" ], "key": "verbs", "title": "The five verbs" }, { "blurb": "Systems, types, fields and closed enums.", "code": "02", "concepts": [ "system", "type", "field", "enum" ], "key": "type-model", "title": "The type model" }, { "blurb": "Governed actions, ordered workflows, and reads.", "code": "03", "concepts": [ "action", "workflow", "query" ], "key": "behaviour", "title": "Actions & workflows" }, { "blurb": "draft -> checked -> bound -> hardened.", "code": "04", "concepts": [ "draft", "checked", "bound", "hardened" ], "key": "maturity", "title": "The maturity ladder" }, { "blurb": "Plasma -> Gas -> Liquid -> Solid -> Crystal.", "code": "05", "concepts": [ "Plasma", "Gas", "Liquid", "Solid", "Crystal" ], "key": "crystallisation", "title": "Crystallisation phases" }, { "blurb": "compile, route, view, agent, context, runtime.", "code": "06", "concepts": [ "compile", "route", "view", "agent", "context", "runtime" ], "key": "surfaces", "title": "Surfaces & lowering" }, { "blurb": "Authority stack, preview-by-default, VSL, Varro.", "code": "07", "concepts": [ "Authority Stack", "preview-by-default", "VSL", "Varro" ], "key": "governance", "title": "Governance & principles" } ], "schema": "varro-edukg.agent-pack.v1", "site": { "title": "Varro eduKG", "url": "https://varro.mentormind.com.au" } }