Veris

中文 README | English Language Guide | 中文语法书

Veris is a verification-first, agent-oriented language prototype. During the pre-self-hosting phase, the compiler remains implemented in C++ and the project stays in the 0.1.x line. The current release line is 0.1.2. Strict local V2 parity currently covers 22/22 public examples/ targets with native execution and fallback_used=false.

Current Public Surface

• source suffix: .vrs
• compiler entrypoint: verisc
• commands: check, run, test, dump-ast, fmt, vet
• implemented syntax: package, import, pub, type, struct, enum, const, impl, task, func, test, let, :=, if, when, match, for, defer, return, say, expect, break, continue
• import surface: relative same-package composition via import "./file.vrs" plus workspace package imports such as import "std/text/scan.vrs" or import "core/collections/text_set/text_set.vrs"; non-relative imports derive the alias from the final file name when as alias is omitted
• compatibility syntax: do print(...), verify stdout == ...
• contracts: callable effect and require, entrypoint authorize, task/test limit, dual-use guard
• type surface: int, bool, text, transparent type Name = ExistingType aliases, named types, []T, map<K,V>, typed params, typed returns, typed let, typed const
• data features: struct literals, field access, enum variants, payload enum variants, list literals, map literals, list indexing, list index assignment, contextual empty [] inference, for item in items, for index, item in items, for key, value in table
• builtin methods: len() on text / []T / map<K,V>, int.to_text(), list push/pop/pop_or/get_or/first_or/last_or/remove/clear/slice, map has/get/get_or/put/remove/clear/keys/values, text at/get_or/first_or/last_or/slice/trim/find/split/join/compare/parse_int_or/repeat/replace/starts_with/ends_with/contains
• bootstrap-core namespaces: ascii.is_space/is_digit/is_alpha/is_alnum/is_lower/is_upper/is_hex_digit/lower/upper, math.abs/min/max/clamp
• importable library packages: std/alg/basic.vrs, std/text/scan.vrs, std/text/builder/builder.vrs, std/source/span.vrs, std/source/line_map.vrs, std/source/cursor.vrs, std/text/escape.vrs, std/path/path.vrs, std/diag/render.vrs, std/diag/report.vrs, core/collections/text_set/text_set.vrs, core/collections/int_set/int_set.vrs, core/collections/text_text_map/text_text_map.vrs, core/collections/text_int_map/text_int_map.vrs, core/collections/text_queue/text_queue.vrs, core/collections/text_stack/text_stack.vrs, core/collections/text_counter/text_counter.vrs, core/source/file_set/file_set.vrs, core/source/text_pool/text_pool.vrs, core/diag/message_buffer/message_buffer.vrs
• sugar: else if, +=, -=, %, defer, low-ambiguity trailing commas
• pattern matching: payload cases, wildcard _, guarded case ... when ..., payload literal atoms, and up to two nested enum-variant layers
• comments: // and /* ... */
• string escapes: \n, \r, \t, \\, \"

Repository Layout

• include/veris/: compiler headers
• src/: lexer, parser, semantics, runtime, driver, CLI
• core/: repo-local bootstrap-first helper packages beyond std/
• tests/: C++ tests and .vrs fixtures
• samples/: legacy and compatibility samples
• examples/: public language examples by difficulty
• scripts/: PowerShell build and test entrypoints
• LANGUAGE.md: public English syntax guide

Local planning and research documents stay under docs/ and are intentionally ignored from git.

Build And Test

.\scripts\build.ps1 -Compiler auto
.\scripts\test.ps1 -Compiler auto
.\scripts\package_stage0.ps1 -Compiler auto
.\scripts\bootstrap_v2_stage0.ps1 -Command test
.\scripts\bootstrap_v2_stage0.ps1 -Command selftest
.\scripts\bootstrap_v2_local.ps1 -Command trust -Target examples/intermediate/trust_manifest
.\scripts\bootstrap_v2_local.ps1 -Command lock -Target examples/intermediate/trust_manifest
.\scripts\bootstrap_v2_local.ps1 -Command fuzz
.\scripts\bootstrap_v2_local.ps1 -Command compare -Target examples/advanced/bootstrap_lexer
.\scripts\bootstrap_v2_local.ps1 -Command matrix -Target examples
.\scripts\benchmark_v2.ps1 -SkipBuild
.\scripts\pre_commit_audit.ps1
.\build\bin\verisc.exe vet examples\advanced\symbol_table
.\build\bin\verisc.exe fmt path\to\file.vrs

If you want to force MSVC, run the scripts from a Visual Studio developer shell and pass -Compiler cl. Run .\scripts\pre_commit_audit.ps1 before each commit so ignored local planning files and docs/ content do not get staged by mistake.

Syntax Snapshot

struct AgentPlan {
    mode: Mode,
    retries: int
}

enum Mode {
    Safe,
    Agent
}

impl AgentPlan {
    func label() -> text {
        match self.retries {
            case 0 {
                return "idle"
            }
            case _ when self.mode == Mode.Agent {
                return "agent"
            }
            case _ {
                return "safe"
            }
        }
        return "unknown"
    }
}

task run_demo {
    effect stdout.write
    limit steps <= 16
    limit stdout_len <= 8
    guard stdout == "agent"

    let plan: AgentPlan = AgentPlan { mode: Mode.Agent, retries: 2 }
    say plan.label()
    expect stdout is "agent"
}

task and test are contract-native. Each runnable unit must declare at least one effect, one limit, and one guard. func and impl methods may declare effect and require clauses and otherwise remain implicitly pure. Runnable entrypoints may bind capability tokens with authorize <token> for <effect> "<scope>". Direct calls are checked against the caller's declared effects and required tokens, so helper calls cannot silently escape either the effect model or the capability model. Static impl calls are also supported in low-ambiguity form: Type.method(...).

Current external builtins are:

• file.read_text(path)
• file.exists(path)
• file.sha256(path)
• file.write_text(path, content)
• network.get_text(url)
• network.post_text(url, body)
• tool.call_text(name, input)
• tool.call_map(name, input)
• term.read_key()
• term.poll_key()
• term.style(style, text)
• term.write(text)
• term.clear()
• term.hide_cursor()
• term.show_cursor()
• clock.sleep_ms(milliseconds)

term.style is intentionally narrow in v1. It is a pure builtin that returns ANSI-styled text, so terminal UIs can stay as simple string assembly instead of growing a separate rich-text object model before self-hosting.

Current bootstrap-core helpers for self-hosting-oriented code are:

• ascii.is_space(text)
• ascii.is_digit(text)
• ascii.is_alpha(text)
• ascii.is_alnum(text)
• ascii.is_lower(text)
• ascii.is_upper(text)
• ascii.is_hex_digit(text)
• ascii.lower(text)
• ascii.upper(text)
• math.abs(int)
• math.min(int, int)
• math.max(int, int)
• math.clamp(int, int, int)
• int.to_text()
• text.find(part)
• text.split(separator)
• separator.join(parts)
• text.compare(other)
• text.parse_int_or(fallback)

Current manifest and lock helpers in the local V2 launcher are:

• scripts/bootstrap_v2_local.ps1 -Command trust -Target <package>
• scripts/bootstrap_v2_local.ps1 -Command lock -Target <package>
• scripts/bootstrap_v2_local.ps1 -Command fuzz

trust verifies veris.manifest plus veris.lock with SHA-256 checksums before V2 check / run / test / dump-ast continue. lock regenerates veris.lock for a manifest-enabled package. fuzz runs the current deterministic parser/trust smoke corpus under tests/fuzz/seeds/.

Current importable std packages are:

• import "std/alg/basic.vrs" or import "std/alg/basic.vrs" as alg
• import "std/text/scan.vrs" or import "std/text/scan.vrs" as scan
• import "std/text/builder/builder.vrs" or import "std/text/builder/builder.vrs" as builder
• import "std/source/span.vrs" or import "std/source/span.vrs" as span
• import "std/source/line_map.vrs" or import "std/source/line_map.vrs" as lines
• import "std/source/cursor.vrs" or import "std/source/cursor.vrs" as cursorutil
• import "std/text/escape.vrs" or import "std/text/escape.vrs" as escape
• import "std/path/path.vrs" or import "std/path/path.vrs" as pathutil
• import "std/diag/render.vrs" or import "std/diag/render.vrs" as diag
• import "std/diag/report.vrs" or import "std/diag/report.vrs" as report
• import "core/collections/text_set/text_set.vrs" or import "core/collections/text_set/text_set.vrs" as text_set
• import "core/collections/int_set/int_set.vrs" or import "core/collections/int_set/int_set.vrs" as int_set
• import "core/collections/text_text_map/text_text_map.vrs" or import "core/collections/text_text_map/text_text_map.vrs" as text_text_map
• import "core/collections/text_int_map/text_int_map.vrs" or import "core/collections/text_int_map/text_int_map.vrs" as text_int_map
• import "core/collections/text_queue/text_queue.vrs" or import "core/collections/text_queue/text_queue.vrs" as text_queue
• import "core/collections/text_stack/text_stack.vrs" or import "core/collections/text_stack/text_stack.vrs" as text_stack
• import "core/collections/text_counter/text_counter.vrs" or import "core/collections/text_counter/text_counter.vrs" as text_counter
• import "core/source/file_set/file_set.vrs" or import "core/source/file_set/file_set.vrs" as file_set
• import "core/source/text_pool/text_pool.vrs" or import "core/source/text_pool/text_pool.vrs" as text_pool
• import "core/diag/message_buffer/message_buffer.vrs" or import "core/diag/message_buffer/message_buffer.vrs" as message_buffer

Current std/ helpers now cover:

• alg.contains_text / contains_int / index_of_text / index_of_int / sorted_texts / sorted_ints / reverse_texts / reverse_ints / is_sorted_texts / is_sorted_ints / binary_search_text / binary_search_int / merge_sorted_texts / merge_sorted_ints / dedup_sorted_texts / dedup_sorted_ints / sum_ints / count_text / count_int
• scan.trim_ascii / split_lines / split_non_empty_lines / line_count / is_ascii_ident / skip_ascii_space / starts_with_at / skip_horizontal_space / skip_inline_trivia / scan_ident_end / scan_decimal_end / scan_line_end / scan_newline_end / scan_until / scan_line_comment_end / scan_block_comment_end / scan_operator_end / scan_quoted_end / scan_string_end / escape_basic / quote / visible_char
• builder.new / Builder.append / Builder.append_line / Builder.append_builder / Builder.append_if / Builder.count / Builder.finish
• span.new / span.merge / span.cover / Span.width / Span.contains / Span.merge / Span.cover / from_source / line_count / line_at / column_at / cursor / move_to / at_end / peek / peek_by / peek_next / peek_text / match_text / advance / advance_by / consume_text / consume_any_text / advance_if_text / match_any / skip_ascii_space / slice / rest / where / where_to
• pathutil.normalize_slashes / clean / join / resolve_import / dirname / basename / extension / without_extension / change_extension / package_key / is_subpath
• diag.header / note / gutter / caret / excerpt / labelled_excerpt / Report / new / format / source_line / format_source / render / render_all / render_file / render_file_all / render_section / render_file_group / error / warning / info

Current guardrail-style guards are:

• guard file.path("scope")
• guard network.host("host")
• guard tool.name("tool")

Examples

• examples/basic/hello_comments.vrs
• examples/basic/list_walk.vrs
• examples/intermediate/model_switch.vrs
• examples/intermediate/typed_dispatch.vrs
• examples/intermediate/payload_tokens.vrs
• examples/intermediate/text_toolbox.vrs
• examples/intermediate/bootstrap_text_scan.vrs
• examples/intermediate/bootstrap_tokenizer.vrs
• examples/intermediate/std_packages.vrs
• examples/intermediate/std_algorithms.vrs
• examples/intermediate/core_collections.vrs
• examples/intermediate/core_tooling.vrs
• examples/intermediate/trust_manifest/
• examples/intermediate/guarded_methods.vrs
• examples/intermediate/effect_pipeline.vrs
• examples/intermediate/capability_contracts.vrs
• examples/advanced/agent_suite/
• examples/advanced/agent_router/
• examples/advanced/symbol_table/
• examples/advanced/bootstrap_buffer/
• examples/advanced/bootstrap_lexer/
• bootstrap/v2/
• examples/advanced/terminal_snake/

examples/advanced/agent_router/ is the current VRS showcase. It models route selection for an agent runtime using typed structs, typed functions, []Route, list iteration, index access, and package tests.

examples/advanced/symbol_table/ is the current compiler-adjacent showcase. It models a keyword table with map<text,int>, payload enums, exhaustive pattern matching, and package tests.

examples/advanced/bootstrap_buffer/ is the current bootstrap-oriented showcase. It models a small token buffer with list mutation, text slicing, list indexing, and package tests.

examples/advanced/bootstrap_lexer/ is the current V2 lexer-and-tools probe. It demonstrates public package exports, imported type annotations, exported impl methods, text-builder helpers, source spans, and pure Veris diagnostic rendering around a small scanner loop.

bootstrap/v2/ is the current runnable second-generation bootstrap skeleton. It keeps the production compiler in C++, but now also exercises pure-Veris multi-line lexing, source cursors, parser-ready token stream helpers such as peek_by / peek_next / skip_newlines / consume_* / recover_until_*, a narrow frontend model for declarations plus structured nested body statements, declaration parsing for package, non-relative imports with explicit or derived aliases, type, struct, enum, const, impl, task, test, when, and a pure func subset, transparent type aliases, low-ambiguity static impl calls, flattened method summaries, package export aggregation, line mapping, escaping, diagnostic report assembly, a semantic-first binder for package-level names and callable contracts, typed local/const/return checking, struct-literal and indexed-assignment validation, direct-call arity/type checks, guarded match case ... when ... validation, enum-match exhaustiveness, nested payload-pattern binding validation, boolean validation for if / when / expect / while-style for, scope-aware checking for nested if / when / match / for, loop-only break / continue checks, low-ambiguity foreach header checking including for key, value in map, bootstrap import signature understanding for std/... plus the current repo-local core/collections/*, core/source/*, and core/diag/* families, manifest-and-lock trust verification through veris.manifest / veris.lock plus SHA-256 checks, index-backed runtime lookup for callables/types/consts, a split native runtime stack (runtime_support / runtime_dispatch / runtime_eval / runtime_control) for easier V2 evolution, library-mode package checks through compile_library_package(...), local driver reports through check_target(...), native V2 foreach runtime over list, map, and text, a simple file-compile probe over samples/simple_module.vrs, a multi-file package frontend probe over samples/frontend_pkg/main.vrs, and semantic/runtime regression packages under samples/semantic_pkg, samples/semantic_bad, samples/typed_pkg, samples/typed_bad, samples/body_pkg, samples/body_bad, samples/match_pkg, samples/match_bad, samples/static_pkg, samples/runtime_map_foreach.vrs, samples/runtime_algorithms.vrs, samples/runtime_core_sets.vrs, samples/runtime_core_tooling.vrs, and samples/trust_pkg/.

scripts/bootstrap_v2_stage0.ps1 is the stage0 launcher for the bundled bootstrap workspace. It reuses the packaged verisc.exe under build/stage0/veris-stage0 and runs check, run, test, dump-ast, or selftest against the bundled bootstrap/v2 workspace or another bundle-relative target. The selftest flow also smoke-tests the bundled bootstrap-oriented examples bootstrap_text_scan, bootstrap_tokenizer, bootstrap_buffer, and bootstrap_lexer.

scripts/bootstrap_v2_local.ps1 is the local second-generation development launcher. It stages a throwaway V2 workspace under build/v2_local/, runs V2-native check and dump-ast through the pure-Veris driver layer, exposes lock to regenerate veris.lock, exposes trust to verify manifest-enabled packages before execution, exposes fuzz for the deterministic parser/trust smoke corpus, exposes compare for bootstrap-target parity snapshots, and exposes matrix so the local V2 compiler can batch-check the entire examples/ tree and emit an aggregate report under build/v2_local/reports/. compare and matrix now skip V1/V2 dump collection by default to keep strict parity checks focused on compile/runtime behavior; pass -IncludeDump only when you explicitly need AST payloads in the report. run and test still support an explicit non-strict fallback path for unsupported targets, but -Strict disables that bridge and records per-target run_status, test_status, fallback_used, and aggregate strict readiness in the report. The current strict baseline is 22/22 public example targets with native parity and fallback_used=false, so bootstrap judgments should use the strict non-interactive gate rather than the fallback-friendly path.

examples/advanced/terminal_snake/ is the current interactive runtime showcase. It uses the first-generation C++ compiler plus the terminal/time runtime surface to run a playable terminal snake with menu selection, obstacles, difficulty presets, deterministic food routing, ANSI color styling, correct newline rendering, and package-level rule tests. It also ships with examples/advanced/terminal_snake/run_snake.bat for one-command local build-and-run or package tests through the first-generation compiler.

examples/intermediate/guarded_methods.vrs is the current syntax showcase for impl methods, guarded wildcard matches, and safer builtin helpers.

examples/intermediate/effect_pipeline.vrs is the current effect/capability showcase. It demonstrates pure helpers, effectful helper functions, effectful impl methods, and safe-first edge helpers such as first_or / last_or.

examples/intermediate/capability_contracts.vrs is the current capability showcase. It demonstrates require, authorize, resource guardrails, workspace-scoped file reads, built-in tool invocation, and the current V2-native capability-runtime parity path.

examples/intermediate/bootstrap_text_scan.vrs is the current bootstrap-core showcase. It demonstrates indexed foreach, ASCII-oriented helpers, small math helpers, and text cleanup operations that are useful when the future self-hosted compiler starts doing scanning, token cleanup, and diagnostics assembly in Veris itself.

examples/intermediate/bootstrap_tokenizer.vrs is the current bootstrap-tokenizer showcase. It demonstrates top-level and local const, safe trailing commas, text find/split/join/parse_int_or, and the newer ASCII classification helpers in a scanner-like flow.

examples/intermediate/std_packages.vrs is the current package-import showcase. It demonstrates import "std/..." as alias, imported const/function access, int.to_text(), bootstrap-oriented path/text helpers such as pathutil.resolve_import, immutable builder composition, source-cursor span coverage, parser-core helpers such as scan.starts_with_at and cursor.rest, and pure Veris diagnostic reporting helpers such as report.render_file.

examples/intermediate/std_algorithms.vrs is the current compiler-core helper showcase. It demonstrates std/alg/basic, low-ambiguity static impl calls such as KeywordTable.seed(), deterministic sorting/dedup helpers, reverse/merge helpers, and binary-search/count/sum style bootstrap utilities.

examples/intermediate/core_tooling.vrs is the current bootstrap-tooling showcase. It demonstrates ordered text maps, ordered text-to-int maps, queue/stack helpers, counted text aggregation, source file interning, pooled text storage, and buffered diagnostic entries in one repo-local core/ pipeline.

examples/intermediate/trust_manifest/ is the current package-authenticity showcase. It demonstrates veris.manifest, veris.lock, SHA-256 verification, file guards, workspace-scoped asset reads, and the local V2 trust / lock workflow.

Direction

Veris is being shaped around a complete ecosystem from the beginning:

• precise compile diagnostics
• deterministic syntax for LLM generation
• typed data flow that is harder for agents to misuse
• direct effect coverage checks across helper calls
• direct required-token coverage checks across helper calls
• a compiled instruction IR between parsing and runtime execution
• built-in test discovery
• built-in formatting and vet-style static review
• vet warnings for discarded bootstrap stream/cursor results and unused public helper surfaces
• safer collection/text helpers that reduce bootstrap-time crash surfaces
• compiler-core algorithm helpers that keep early self-hosted code out of ad-hoc handwritten loops
• builtin-first bootstrap helpers for scanner/parser/diagnostic code before a full standard library exists
• aliased package imports plus a first pure Veris std/ tree for bootstrap-oriented helpers
• transparent type aliases for bootstrap-facing naming without expanding runtime surface area
• explicit pub export surfaces so cross-package reuse stays narrow, auditable, and low ambiguity
• contextual empty-list inference only when the surrounding type is explicit, to keep diagnostics predictable while still making bootstrap code less noisy
• static top-level constant cycle detection, so bootstrap configuration graphs fail at compile time instead of only at runtime
• a runnable bootstrap/v2 workspace that keeps V2 experimentation executable before self-hosting
• readonly const bindings for frozen bootstrap configuration and token metadata
• builtin-first terminal styling so interactive bootstrap tools can render readable text without waiting for a full stdlib/package layer
• scoped built-in file/tool/network capabilities instead of ambient access
• local terminal/time effects that keep interactive tooling explicit without exposing broader process access
• explicit data modeling for safer execution
• future package tooling and a richer standard library

Future Provider Adapter

This is a future ecosystem direction, not a claim about the current compiler/runtime implementation.

• Tool-choice must first pass through a provider-neutral intermediate layer before it is lowered into provider-native request fields.
• For Gemini, the tool-choice mode maps to functionCallingConfig.mode.
• Forced-tool or required-tool flows map to allowedFunctionNames.
• Before a request is sent, tool schemas should be narrowed to the provider-supported OpenAPI-style subset instead of assuming one provider's full schema surface works everywhere.

Thanks

Thanks to the LinuxDo community for feedback, discussion, and practical language/ecosystem inspiration during the early Veris design phase.

See LANGUAGE.md for the current public grammar and recommended style, or LANGUAGE.zh-CN.md for the Chinese edition.