receiver.name(args) calls a builtin whose first parameter has the receiver’s type. The checker picks the module from the static type (String, Bytes, List, Map, Set, Float, Result, Range, Int, JSON.Value through JSON, and Codec[T] through Codec); there is no dynamic dispatch. s.strip is String.strip(s), and n.to_s is Int.to_s(n). The methods of a codec are also functions, Codec.decode(c, s), as String.upcase is. Without parentheses, receiver.name on a non-struct value is a method without arguments (s.length, r.ok?). On a struct, .name is a field. Structs and enums have no methods. The forms on a type name are Type.members, the list of the fields of a struct (docs/grammar/06-semantics.md, “Structs and lists”), and Type.codec, its codec (JSON, below).

A builtin has its Ruby name (strip, include?, start_with?, to_i, to_f, to_s and join); an old name (trim, contains?, to_int, String.from_int, String.join) is CHECK-UNKNOWN-METHOD, or CHECK-UNKNOWN-NAME for a function, with the Ruby form as help. Ruby aliases are the module functions named in the library pages: push, select, key?, and to_s and inspect on any data value. Ruby’s other names for a method work too, and the texts show only the first: length and size on String, Bytes, List, Map, Set and Range; collect for map, inject for reduce and detect for find (on List and Lazy); member? for include? on List, Set and Range; include? and member? for key? on Map. Two differ from Ruby: to_i and to_f on text return a Result ("abc".to_i is an error, not 0), and to_i! and to_f! halt on bad text. An unknown method is CHECK-UNKNOWN-METHOD.

x.to_s is the text "#{x}" gives: a String as is, a JSON.Value as its JSON text, an Error as its message, and any other data value in its inspect form ([1, 2], ok(3), Item(name: "a")). An Error inspects as the error(...) call that builds it, without the fields that hold their default and without location, both alone and as the payload of a failed Result. Inside a list, a JSON.Value shows as <JSON.Value>. Functions, tasks, handles, C.Pointer values and resources have no to_s, so printing or interpolating one is CHECK-TYPE-MISMATCH. Unlike Ruby, nil.to_s is "nil". x.inspect keeps a string’s quotes; it is for display, not valid source.

Values are immutable: a method never changes its receiver, so xs.push(2) returns a new list. A builtin without effects whose non-Void result is dropped is CHECK-UNUSED-VALUE; write xs = xs.push(2). Builtins with effects, functions ending in !, and builtins that take a function are exempt, except that a dropped Result is CHECK-UNUSED-RESULT for any call (see “Result and propagation” in the semantics). A negative literal receiver needs parentheses: (-5).to_s.

Minimal builtin functions #

The library reference describes every builtin: signatures, behaviour, costs, limits and runtime errors. agentica help NAME prints one signature. This section keeps what the language fixes.

puts(value) writes the value’s to_s and a newline; print writes without one. gets and gets! are IO.gets and IO.gets!, and may drop their parentheses (line = gets!.strip). Map, Set and List are builtin modules whose generic functions the checker treats specially: see List, Map and Set.

format(fmt, args...) is Ruby’s format. Its first argument must be a one-line "..." string literal (CHECK-FORMAT-LITERAL), which the checker reads: a bad conversion is CHECK-FORMAT-SPEC at its characters, and the arguments are checked against the conversions (CHECK-ARITY, CHECK-TYPE-MISMATCH). The conversions are in numbers. Only the function name is reserved: def format is CHECK-REDEFINED-NAME, and a variable, parameter or field may be named format.

A builtin family groups builtins under one reserved name, as Ruby’s OpenSSL::Cipher does: its members are written Family.Member and their functions Family.Member.fn(args), two levels at most (OpenSSL.Cipher.aes_256_gcm_encrypt(key, iv, data), OpenSSL.Random.uuid, data |> OpenSSL.Digest.sha256()). A member is a group of functions or a builtin type. A member the family lacks is CHECK-UNKNOWN-NAME, with the members in the help; a group of functions where a type is wanted is CHECK-UNKNOWN-TYPE. The one family today is OpenSSL (Digest, HMAC, Cipher, CMAC, KDF, RSA, Random).

Callbacks (List.map, select, reduce, each, any?, all?, sort_by and the other methods that take a function) take a block, &name or a function variable. Parameter and return types must match exactly, and a map callback returns data, not Void. Annotated block parameters let an empty list or an empty reduce initial value infer its type.

Lazy[T] is a lazy pipeline: an immutable recipe of a source and steps, not a cursor. A Lazy has no ==, no to_s and no JSON form (CHECK-TYPE-MISMATCH, CHECK-NOT-ENCODABLE); IO.inspect prints <Lazy>. A List method on a Lazy and a step that only Lazy has on a List or Range are CHECK-UNKNOWN-METHOD. A block after each_slice on a List is CHECK-BLOCK-TARGET, and File.foreach(...).each do ... end as one chain is CHECK-LAZY-NO-STEP. A failed try in a block of a Lazy method ends the pipeline, whatever the block’s result type. Sources, steps and terminals are in the Lazy page.

JSON #

JSON is reserved; JSON.Value, JSON.Field and JSON.Node are members of its family. A JSON.Value has no constructor, equality, fields or indexing. The functions, their errors, the schema and the text they read and write are in the JSON page. The rules that the checker enforces:

  • JSON.decode(source, T) and JSON.schema(T) take a named struct or enum type, not a value, and so does T.codec; bare type names are valid only for these. A type name followed by [ in an expression is always a type with arguments (Box[Int], Lib.Box[Int]), never an index. JSON.decode also takes List[T] and Map[String, T] of such a type (or of a field type below); schema and codec refuse them (CHECK-TYPE-MISMATCH). Fields and payloads may be Int, Float, Bool, String, lists, String-keyed maps, nested or recursive structs and enums, generic struct instances whose fields are such types after substitution (semantics, generic structs), and Optional of those (and JSON.Field, for a struct field); any other nested type, a generic enum instance included, is CHECK-NOT-DECODABLE.
  • JSON.encode and JSON.from accept Int, Float, Bool, String, Nil (as null), JSON.Value, lists, String-keyed maps, Optional, structs and user enums of those, whose struct fields may also be JSON.Field. An instance of a generic struct or enum counts by its fields or payloads after substitution (Box[List[Int]], Maybe[Int]). Results, builtin enums (TaskExit) and Int-keyed maps are CHECK-NOT-ENCODABLE. Untyped empty containers need an annotation.
  • A user enum is a tagged object {"tag": "Rect", "values": [1.0, 2.0]}: tag is the variant name and values the payloads in order. The page has the errors and the schema (a oneOf). A JSON.Field in a payload is CHECK-JSON-FIELD-PLACE.
  • T.codec takes the targets of decode, with its diagnostics (a value is CHECK-UNKNOWN-METHOD), and gives a Codec[T]: the JSON of T and its members as a value, for generic code, which cannot call decode on its type parameter. codec.decode, codec.encode and codec.from are the JSON functions of T, and codec.members is the List[StructMember] of T.members (empty for an enum). Codec is reserved as a type name and as an import alias (import Codec from "x" is CHECK-REDEFINED-NAME). A codec follows the rules of an Fn value: it may be a parameter, a struct field or a list item, and it has no to_s, inspect or equality and is no constant or ATS value. IO.inspect of a type that holds a codec is CHECK-TYPE-MISMATCH.

Optional values in JSON #

Optional[T] is JSON’s null or a T, anywhere a type is: a struct field, a list item, a map value, an Optional item, or the whole value of JSON.encode and JSON.from. none is null, some(x) is x, and a missing key of an Optional struct field decodes as none.

  • Optional[Nil] is CHECK-NOT-ENCODABLE or CHECK-NOT-DECODABLE, since some(nil) would be written as null. An Optional cannot hold a JSON.Field (Optional[JSON.Field[T]] is CHECK-JSON-FIELD-PLACE), and a JSON.Field[Optional[T]] is CHECK-NOT-ENCODABLE or CHECK-NOT-DECODABLE: use Optional[T] when a missing key and null mean the same, and JSON.Field[T] when they differ.
  • JSON.decode, JSON.schema and T.codec take a struct or enum name, so a top-level Optional is decoded as a field of a struct.

Optional and nullable fields (JSON.Field) #

A struct field of type JSON.Field[T] keeps the three states of a key apart in typed JSON: absent, null, or a value. JSON.Field is a builtin generic enum:

enum JSON.Field[T]
  Absent
  Null
  Value(T)
end
  • The variants are always qualified (JSON.Field.Value(x)). Absent and Null need an expected type, like any nullary variant of a generic enum (CHECK-ENUM-TYPE-INFERENCE otherwise); a struct field gives one. A case needs the three arms or a _ arm, which is how a program treats absent and null alike.
  • Where: in the type of a JSON.decode or JSON.schema target or of a JSON.encode or JSON.from argument, JSON.Field may only be the direct type of a struct field. A list item, a map value, an Optional item, a nested JSON.Field[JSON.Field[T]] or the whole argument of JSON.encode or JSON.from is CHECK-JSON-FIELD-PLACE, at the target or argument. A type argument counts after substitution: in Box[JSON.Field[Int]] (struct Box[T] with value: T) the field is a direct JSON.Field field, but items: List[T] or f: JSON.Field[T] with that argument is CHECK-JSON-FIELD-PLACE. This check comes first, so List[JSON.Field[Nil]] is CHECK-JSON-FIELD-PLACE. JSON.Field[Nil] as a field is CHECK-NOT-DECODABLE or CHECK-NOT-ENCODABLE, since Value(nil) would be written as null. A bare JSON.Field target is CHECK-UNKNOWN-TYPE.
  • Outside JSON, JSON.Field[T] is an ordinary enum value: locals, parameters, lists and maps may hold it, it prints when T does (JSON.Field.Value(30)), and it has no ==.

Builtin discovery and execution budget #

agentica help NAME --json prints the name, arity, parameter types, result, signature, effects and description, from the catalog that checking and execution use. A parameter with a default also has default, its source text ("0"), and the arity counts every parameter. ruby is the signature in the Ruby method form (list.select(block: Fn[A, Bool]) -> List[A] for List.filter), or null for a builtin with no method form. The help text and the helps of diagnostics write that form too (list.select, not List.filter), while both names stay accepted. Effects are informational (I/O, tasks, or test). An unknown target exits 2, with a hint when the name is a close builtin or one from another language that the checker knows (Hash.new, int). A name that other languages use for a builtin (len, List.push, value!) is not unknown: it exits 0 with the builtins it stands for, and --json prints {"alias": NAME, "builtins": [...], "hints": {...}}, builtins holding what help NAME --json prints for each. agentica help --json with no NAME prints every public builtin and builtin type as one JSON array, sorted by name, each element exactly what help NAME --json prints. A builtin type that a program can name (File.Info, JSON.Field, File.Handle, JSON.Value; not the std-only HttpWire.* and LogRegistry.*) has name, kind (struct, enum or opaque), signature (struct File.Info), description, and the fields of a struct or the variants of an enum in the shape of help std/MODULE.NAME --json; a function has no kind.

The query commands (doc, help std/..., outline, type-at, symbol and refs) are described for users in Command line. None of them runs the program. The contract that page leaves out:

  • agentica doc PATH and outline FILE take a source file or a std/ module name and only lex and parse it, so its imports need not exist; a file that re-exports a name (export Url.parse) is also linked, and a re-export whose module does not link is left out of outline. A lex or parse error exits 1; an unreadable path exits 2 (QUERY-USAGE in outline).
  • agentica help std/MODULE[.NAME] --json: a module is {module, doc, items: [{kind, name, summary}]}, and a name has the help NAME --json fields that apply (name, arity, parameters, result, signature), description (the whole doc or null), summary, kind and module, and no effects. A name that is empty after the dot is QUERY-USAGE.
  • Positions of type-at and refs count from 1, in code points as diagnostics count them. The kind of the JSON answer of type-at is an open set: a client accepts a value it does not know. A bad position is QUERY-USAGE and a position on no expression is QUERY-NO-EXPRESSION, both exit 2 (section 7); an error of the program is its own diagnostic and exits 1.
  • --stdin replaces the text of FILE with standard input: before the position in type-at --stdin FILE:LINE:COL, and with a NAME in symbol and refs the text is searched as one more file.
  • With --partial (type-at, and refs with a position and no PATH; outline accepts it and ignores it) a program in which some functions do not check is answered from the functions that do: the answer has "partial": true and diagnostics, and exits 0. A name in a function that did not check is answered by its definition after linking, with a type of null. The references to a function, struct, enum, alias, resource, constant or variant are complete, and so are those of a local of a function that checks; a field or a builtin needs every function checked. A program that does not link, or a position that cannot be answered this way, is the first diagnostic and exits
    1. A NAME or a PATH with --partial is QUERY-USAGE.
  • symbol and refs link the files under PATH (default .) together and everything they import; one that does not lex, parse or link is listed under skipped with its first diagnostic while the others still answer (exit 0), except the FILE of a refs position, which must link. If none links, the first diagnostic is the answer (exit 1). A match has kind (function, struct, enum, alias, resource, constant, field, variant or builtin), module, exported (private declarations too), signature, doc and spans; a builtin has help, the object of agentica help NAME --json. The answer of symbol is {version, command, query, matches, skipped}.
  • refs lists every reference to a declaration (a function, struct, enum, variant, field in a read, a construction and a with, constant, type alias, resource, local or builtin); the definition is not a reference. The linker and the checker decide what a name is, so two fields of one name in two structs, or a name bound in two sibling blocks, are never mixed. A parameter of a function is also used at each call that gives it by name (verbose of check(gen, verbose: true), kind argument); a position on that name picks the parameter, in type-at too. A NAME that nothing declares is QUERY-NOT-FOUND; one that several declarations answer to is QUERY-AMBIGUOUS-NAME, whose help lists each as FILE:LINE:COL. A position on a name in a declaration picks it, and so does one on a name of an import list (make of import {make} from "models"), which selects the imported declaration; a position on the module alias of Models.total(u) selects the function total, not the module.

agentica --max-steps N program.agc limits a run to N expression or statement entries across all tasks (N a positive integer; runs are unlimited by default, and checking never spends the budget). Exhaustion is RUNTIME-STEP-LIMIT at the next node. It is not a wall-clock or blocking-I/O timeout. With more than one scheduler the limit can trip a little late; --schedulers 1 keeps the exact count.

At the end of a run the VM waits for the buffered writes of every open file, for the output of stdout and stderr that a pipe has not taken yet, and then for the frees of what native code still owns (see How a run ends). The wait is always bounded by --flush-timeout MS or AGENTICA_FLUSH_TIMEOUT_MS (the flag wins, a bad value exits 2, and there is no way to turn the limit off; the default and range are in Command line). On timeout, the run ends with the same exit code, and stderr gets agentica: file data may not be written: the flush took longer than MS ms (with --json, {"flush_timeout_ms": MS, "warning": "file data may not be written"}); when a native free is what took too long, the warning says native resources may not be freed instead (both, joined by and, when both did).

--schedulers N or AGENTICA_SCHEDULERS sets the number of scheduler threads (the flag wins over a valid variable, an empty variable counts as unset, and a bad value in either exits 2, before the program starts). With more than one, tasks run in parallel and their order is not fixed; --schedulers 1 runs one task at a time in the order of a single run queue. The front end always compiles on one scheduler. agentica test refuses the flag (exit 2); the VMs it starts read AGENTICA_SCHEDULERS.

Everything is allowed by default. --deny-run, --deny-net, --deny-fs and --deny-env each turn off a family of builtins: a call returns an error that begins with denied: and the flag (denied: --deny-fs), and the program goes on. --deny-net stops every connect and listen of TCP and TLS, std/http too, before any DNS lookup. --deny-fs covers every File, Dir and Path call but Path.join, Lazy.write_lines, Lazy.write_bytes, and a TLS call that names a file. --deny-env covers System.env (System.os and System.pid stay on: they hold no secret). Each turns on --deny-native, since native code could do the same. --sandbox is all of them. The flags apply to the program, not to the front end; agentica test gives them to the test files, the step programs and the programs under test, not to its runner. The table of flags is in Command line.

Calls nest at most 10000 deep in each task; a deeper call is RUNTIME-STACK-OVERFLOW at the call. A tail call (return f(...) to a user function, or f(...) as the last expression that gives the function’s value) replaces the caller’s frame and does not count, so deep tail recursion runs. A call inside a larger expression, such as return 1 + f(n - 1), and a call of a builtin are not tail calls.

The bytecode cache #

agentica FILE.agc and each test file of agentica test keep their compiled program in _build/bytecode/ and read it back while the sources are the same (files, ownership checks and flags in Command line). The entry holds the bytes agentica compile writes, the version, build and path of the binary, the SHA-256 of every file the front end read (with agentica.toml and agentica.lock), and what the resolver looked at: each place of the pkg/ search that was empty or held a file, and where each relative import led. A lookup checks them again; any difference, or a damaged entry, compiles the program again and replaces the entry. A run that hits has no front-end diagnostics, since the program checked when it was cached. When the folders fail the ownership checks the run goes on without the cache, and a folder that cannot be written is not an error. The --deny-* flags do not apply to the cache: they are for the program.

Running a compiled program #

agentica compile file.agc -o file.agcb writes a program as bytecode, and agentica run [OPTIONS] [--] file.agcb [ARGS...] runs it on the VM with no front end: nothing is read, checked or compiled. run must be the first word after agentica; after an option it is taken as a source file name and the front end answers with a usage error (exit 2). The options are --max-steps N, --seed N, --flush-timeout MS, --schedulers N, --jit MODE, the --deny-* flags, --sandbox, --source-root DIR (the folder put before the file names that the bytecode stores, except the std/ modules), --ai and --json, each at most once and with the values and limits they have for agentica FILE.agc; --version prints the Agentica version and the versions of the libraries the VM links. The words after the file are the program’s arguments, even when they look like options. The loader treats the file as untrusted, but its native code runs unless a --deny-* flag or --sandbox is given. A file that is not valid bytecode, or whose format or Agentica version is not the binary’s, is refused before anything runs; a source file also gets the hint to run it as agentica FILE.agc. The exit status is the program’s own: System.exit(n), 1 for a diagnostic, and 2 for a command line or a start that fails (a bad option, an unreadable file, bad bytecode), with a message that starts agentica run:.