# Modules

Each file is a module. `import Models from "models"` loads `models.agc` and
gives it the alias `Models`, and `import Util from "../lib/util"` loads
`../lib/util.agc`. The path has no extension. A path ending in `.agc`, an empty
path, a path ending in `/`, or a last part containing a dot (`"models.rb"`,
`"."`, `".."`) is `CHECK-IMPORT-PATH`, so a module file name has no dot apart
from `.agc`: `json.tools.agc` cannot be imported; rename it `json_tools.agc`.

Relative paths resolve from the importing file, not the working directory. Each
file is linked once. Cycles are `CHECK-IMPORT-CYCLE`, missing or unreadable
files are `CHECK-IMPORT-IO`, and invalid paths are `CHECK-IMPORT-PATH`; each is
located at the import.

## Public and private names

A declaration is public, unless it comes after a `private` line: every
declaration above it (constant, struct, enum, type alias, function, module
block) is public, and every declaration after it is private to the file. A file
with no `private` is public as a whole. Imports are never public.

```agentica
LIMIT = 10

def open(id: Int) -> Int = connect(id)

private

BUFFER = 4096

def connect(id: Int) -> Int = id + BUFFER
```

- `private` is the name `private` alone on its line, at the level of the
  declarations of a file or a module block; elsewhere it is an ordinary name.
  `private def f` is `PARSE-TOP-LEVEL-STATEMENT`. A blank line comes before
  and after it (`PARSE-MISSING-BLANK-LINE`); `agentica fmt` keeps it where it
  is.
- A file or block has at most one `private`; a second one is
  `PARSE-SECOND-PRIVATE` at it. There is no `public` to switch back.
- `export` before a declaration (`export def`, `export struct`, `export enum`,
  `export type`, `export NAME = ...`, `export module`) is
  `PARSE-UNEXPECTED-TOKEN` at the `export`, in a file, a module block or an
  extern block. A re-export (`export Alias.name`, below) is the only use of
  `export`; it is public and goes above `private`.
- Reaching a private name (`M.helper`, `import {helper} from "m"`,
  `Counter.step`) is `CHECK-IMPORT-NAME` at the name, with a help that says it
  is private and how to make it public: move it above `private`. For a name
  that the module only imports, the help names the re-export that would pass it
  on (`export Url.parse`). For a `std/` module or a package, which the user
  does not edit, the help only says that the name is private.

A type alias is public in the same way as a struct, enum, function or constant.
An importer can use `Models.Names` or import it
by name with `import {Names} from "models"`; type aliases can also be renamed to
another capitalized name. Aliases can name private types in public signatures;
importers can use values of the alias but cannot name or construct the private
type. Local names stay unqualified. Import aliases are uppercase and cannot
collide with declarations, other aliases, imported names or builtin names.
A module can pass on a name it imports with a re-export (below).

## Unused imports

An import alias that its file never uses is `CHECK-UNUSED-IMPORT`, located at
the alias, with the help `remove import Alias from "path"`. A use is any place
that writes a name with the alias first: a call, a `&function` value, a type
(in an annotation, a signature, a field or a block parameter), a construction,
an enum constructor or a pattern, an enum type and a constant (`Alias.NAME`),
and the alias of a re-export (`export Alias.name`). A regex literal counts as a
use of the `std/regex` import and a `<<~EAG` template as a use of the `std/eag`
import, since each needs it in some form. A use inside a function that nothing
calls counts: the rule is about the text of the file. An import
has no effect besides its names, so removing an unused one never changes what a
program does. The rule holds for every file, `pkg/` libraries and `std/`
included: a package with a stray import fails the build of every program that
uses it.

An alias written without its member (`u: User`, `User(name: "Ana")`, or
`Domain.Some(1)` with `Domain` an alias) is `CHECK-IMPORT-NAME` at the alias,
with the help `write User.<Type>`, not an unused import. A file with a call
`Alias.name` whose first part is no alias, no name of the file and no builtin
module (a mistyped alias) gets `CHECK-UNKNOWN-NAME` from the checker instead.
The first alias never used is reported, imports in source order and files in
link order (the root first), after that file's own resolve errors. Any command
that builds or checks a program (`check`, `run`, `compile`, `test`) reports it.
The query commands (`type-at`, `refs`, `symbol`, `--partial`) do not report it
in the file they are asked about, since an editor adds an import before it
writes the first use; the files that file imports keep the rule.

## Importing names

`import {User, greet} from "models"` brings the exported names `User` and
`greet` into the file, to be used bare, wherever the name can stand: `User` in
annotations and signatures, `User(name: "Ana")` to construct, `greet(user)` or
`user |> greet()` to call (parentheses are required, as for a function of the
file), `&greet` for a function value, and for an enum `Option`, the type
`Option[T]`, the values `Option.None` and `Option.Some(value)` and the patterns
`Option.Some(v)`. Variants are not imported on their own: import the enum. A
function, struct, enum, type alias and constant can all be imported this way.
The two forms mix: a file may import a module with an alias and, on another
line, import names from it, and two lines with the same path are fine (the file
is loaded once). A module imported only by names has no alias, so `Models.` is
not available for it.

An entry may rename: `import {greet as hello, User as Account, Names as Labels}
from "models"` binds local names for those exports. It exists so that two
modules that export the same name can both be imported by name, and so that a
long name can be shortened. A struct, enum or alias is renamed to a type name (a
capital first letter), a function to a lowercase name, a constant to another
constant name (capitals and underscores), and anything else is
`CHECK-IMPORT-RENAME`, located at the new name. The original name is not bound
unless another entry imports it, `{greet as hello, greet as hi}` binds two names
for one function, and messages that print a name show the original name. `as` is
contextual here too, and the original always comes first, so `{as as as_text}`
renames a function called `as`.

A name from an import list joins the names of the file, as a declaration does.
It must not be the name of a declaration of the file, of an alias, of another
imported name (in the same list or in another import line, and the same name
from the same module twice), of a builtin function such as `puts` or `ok`, or of
a reserved type name such as `Int` or `JSON`; each is `CHECK-REDEFINED-NAME`,
located at the name in the braces (at the new name of a rename). A name that
the module does not export, or that is private, is `CHECK-IMPORT-NAME` at the
name, with the help for a private name (above) or a `did you mean` help over
the exports only. These checks run when
the file is loaded, so they are reported at the import, before any use of the
name. A name used as the wrong kind (an
imported struct as the enum of a pattern) is `CHECK-TYPE-MISMATCH`, as with an
alias.

Unused names of an import list are not reported.

## Re-exports

A module can pass on a name it imports, so a small facade file can collect the
API of several files:

```agentica
# web.agc
import Url from "url"
import Parts from "http_parts"

export Url.parse
export Url.Address
export Parts.header_value
```

`export Alias.name` (a function, a constant) and `export Alias.TypeName` (a
struct, enum or type alias) add the name to the exports of the file. There is
no renaming (`as`) and no wildcard (`export Url.*`): a facade that wants
another name writes a wrapper function. `export` is followed by a type name
and a dot only for a re-export; it is not used before a declaration. A
re-export is public: it goes above `private`, and one after it is
`CHECK-DECL-ORDER`.

- The alias must be an import of this file (`import Url from "url"`; a module
  imported only by names has no alias), otherwise `CHECK-IMPORT-NAME` at the
  alias. The module must export the name, otherwise `CHECK-IMPORT-NAME` at the
  name, with a `did you mean` help over the exports. A private name is not
  re-exportable.
- The name must not be the name of a declaration of the file, of another
  re-export or of an import alias of the file: `CHECK-REDEFINED-NAME` at the
  name. So the alias of a facade must differ from the names it re-exports:
  `import Value from "value"` with `export Value.Value` is an error; write
  `import V from "value"` and `export V.Value`.
- It is the same declaration, not a copy. A program that imports both
  `web.agc` and `url.agc` sees `Web.Address` and `Url.Address` as one type, and
  `&Web.parse` and `&Url.parse` are the same function. A re-export of a
  re-export leads to the original declaration, and a re-exported enum brings
  its variants (`Web.Option.Some(x)`). A re-exported constant is read as
  `Web.LIMIT`.
- Inside the file the name is still `Url.parse`: a re-export adds no local
  name.
- A `std/` module may also re-export a builtin record, enum or handle type of a
  std-only module (`HttpWire`, `LogRegistry`, `RegexEngine`), which needs no
  import: `export LogRegistry.Event` in `std/logger` makes `Logger.Event` that
  builtin record, and `export HttpWire.Client` in `std/http` makes
  `HTTP.Client` that handle. Outside `std/` such a re-export is
  `CHECK-UNKNOWN-NAME` at the module name; a name of the module that is no
  record, enum or handle type is
  `CHECK-IMPORT-NAME` at the name.
- Re-exports come with the imports, may follow each other and the imports
  directly, and after a declaration need the blank line
  (`PARSE-MISSING-BLANK-LINE`); they are with the public constants in
  `CHECK-DECL-ORDER`, after the imports: an `import` after a re-export is out
  of order. A
  `##` doc before a re-export is `PARSE-DETACHED-DOC`: the doc stays on the
  original.

## Constants

A public constant (`LIMIT = 100`, above `private`) is visible, and
`import {LIMIT} from "limits"` brings it in by name, like any other exported
name (it can be renamed to another constant name:
`import {LIMIT as MAX_ITEMS} from "limits"`). A constant is read by its bare
name, wherever an expression can stand, in the file that declares it and in a
file that imports it by name. An importer that has the module under an alias
reads an exported constant as `Limits.LIMIT`, like an exported function:
`Limits.NAMES.size`, `Limits.CONFIG.with(port: 81)` and `"#{Limits.LIMIT}"` work
as for a bare constant. A private constant, and a name the module does not
export, are `CHECK-IMPORT-NAME` at the member, with a `did you mean` help for a
near export, as for a function. A constant is no function and no type:
`Limits.LIMIT()` and `x: Limits.LIMIT` are `CHECK-TYPE-MISMATCH`. An imported
name must not collide with a constant of the file, and two constants of the same
name are `CHECK-REDEFINED-NAME`, as for any declaration. A constant is never
changed, so there is no shared state between modules: the value an importer
reads is the value the declaring file computed.

Only the root file supplies the executable `main() -> Void`; imported `main`
functions do not run. Imported calls and tasks share the program's step budget
and resource ownership. There are no wildcard imports, mutable module state or
receiver attachment.

## Module blocks

`module Name ... end` at the top level of a file groups declarations under a
name, so one file can hold several named modules. It is a namespace only:

```agentica
# agents.agc
module Counter
  enum Msg
    Add(Int)
    Get
  end

  def start(initial: Int) -> Int = step(initial, Msg.Add(1))

  private

  def step(count: Int, msg: Msg) -> Int
    case msg
      Msg.Add(n) -> count + n
      Msg.Get -> count
    end
  end
end
```

- The name is capitalized and follows the rules of an import alias: it must
  not be the name of a declaration, an alias, an imported name or a builtin
  name (`CHECK-REDEFINED-NAME`, at the name; at the import when an import line
  takes it). `module name` with a lowercase name is not a block.
- Inside, a block holds what a file holds, with the same layout rules (the
  blank lines and `CHECK-DECL-ORDER`): constants, structs, enums, type aliases
  and functions, generic ones included. An import, a re-export or an extern
  block inside is `PARSE-UNEXPECTED-TOKEN`; a block inside a block is
  `PARSE-NESTED-MODULE`, at the inner `module`. A block may be empty. In the
  file it ranks with the structs and enums for `CHECK-DECL-ORDER`.
- Scope is lexical: the body sees the imports of the file, its top-level
  declarations (private ones too) and the other blocks, and its own names
  bare. One name means one thing in a scope, so a block may not declare a name
  that the file declares or imports, or the name of a block
  (`CHECK-SHADOWED-NAME`, at the name). Two blocks may declare the same name
  (`A.start` and `B.start`): neither sees the other's names bare.
- A block has its own `private` line, with the rules of a file: what is above
  it is public, the rest is private to the block, and a block without one is
  public as a whole.
- Outside the block (the rest of the file and importers) only its public
  names are visible, written `Counter.start`, `Counter.Msg.Add(5)`,
  `Counter.LIMIT`, `Counter.Box[Int]`. A private name is `CHECK-IMPORT-NAME`, as
  for a name a file does not export. Uses inside a block count for
  `CHECK-UNUSED-IMPORT`.
- A public block (above the file's `private`)
  lets an importer use it: `import {Counter} from
  "agents"` binds `Counter` as an alias (`import {Counter as C}` renames it),
  and `import Agents from "agents"` reads `Agents.Counter.start(0)`,
  `Agents.Counter.Msg.Add(5)` and the type `Agents.Counter.Msg`. Any other
  block is private to its file.
- Only the root file's top-level `main` runs, so a block may not declare
  `main` (`CHECK-MAIN`, at the name). There is no mutable module state, and
  `extern module` keeps its meaning.

## Standard library and external libraries

- `import Queue from "std/queue"` loads the standard library embedded at build
  time. Nothing needs to be installed, and local files or external roots cannot
  shadow it. Embedded modules may use relative imports inside `std/`, with
  `..` as long as the path stays in `std/`.
- `std/internal/` holds code that `std/` modules share and that is not API
  (`std/analysis` compiles the pure core of the front end from there). Only a
  `std/` module may import it; any other file gets `CHECK-IMPORT-IO`.
  `agentica doc` and `outline` of it fail as for a missing module: `cannot
  read` (`QUERY-USAGE` in `outline`, exit 2).
- `import Tools from "pkg/acme/tools"` searches for `acme/tools.agc` in order:
  `agc_libs/` beside the root program, or beside `agentica.toml` when the
  project has a manifest (not beside a dependency); the absolute roots in
  `AGENTICA_PATH` (`:`-separated, `;` on Windows), in order;
  `$XDG_DATA_HOME/agentica/lib/` (default `~/.local/share/agentica/lib/`; on
  Windows `%LOCALAPPDATA%/agentica/lib/`); then `/usr/local/share/agentica/lib/`
  and `/usr/share/agentica/lib/` (none on Windows). A first part (`acme`) that
  the manifest declares as a dependency is a package instead, and the search
  does not run for it (see Packages below).

The first existing file wins, and an error in that file does not fall back to
another root. Empty `AGENTICA_PATH` entries are ignored; a relative entry is
`CHECK-IMPORT-PATH`. A root is absolute when it starts with `/` (on Windows: a
drive path such as `C:\libs` or `C:/libs`, a UNC path such as
`\\server\share\libs`, or a path that starts with `/` or `\`; `C:libs` is
relative). On Windows the other separator is part of the entry, and
`XDG_DATA_HOME` and `HOME` are not read: an unset or relative `LOCALAPPDATA`
leaves the user root out. Library paths use forward slashes and reject empty,
`.`, `..`, backslash and colon components. After symlink resolution, the target
must stay inside its root. These checks apply to namespaced imports only:
imports are not a filesystem sandbox. A missing module is `CHECK-IMPORT-IO`.
Diagnostics inside an embedded module name its source, such as `std/queue.agc`.

## Packages (`agentica.toml` and `agentica.lock`)

A package is a git repository of `.agc` files. A project uses packages when an
`agentica.toml` (the manifest) is in the folder of the root file or in a folder
above it; the nearest one counts, and its folder is the project folder. The
search goes up to the root of the file system, so an `agentica.toml` in a shared
parent folder (such as `/tmp`) is read and checked for every script below it,
and a bad one there is `PKG-MANIFEST-INVALID` for each of them. Without a
manifest nothing changes. A build reads the manifest and the lock and loads
packages only from `deps/` beside `agentica.toml`, which `agentica install`
writes (see below). A build never runs git and never uses the network, and it
never reads the package cache. `agentica add` and `agentica update` write the
lock (see below).

```toml
name = "notes"

[dependencies]
sqlite = { git = "https://github.com/owner/sqlite-ac", tag = "v1.2.0" }
json5 = { git = "https://gitlab.com/someone/json5", ref = "3f2a9c1" }
postgres = { git = "https://github.com/owner/packages", tag = "postgres-0.1.0", subdir = "postgres" }

[style]
max_line_width = 119
```

```ruby
import Sqlite from "pkg/sqlite/db"
```

- The manifest knows `name`, `agentica`, `[dependencies]`, `[native]`,
  `[style]`, `[workspace]` (below) and `[tool]`, a table of tables
  (`[tool.NAME]`) that other tools own: Agentica reads nothing inside them and
  checks only that `tool` and each `tool.NAME` is a table. Outside `[tool]`, an
  unknown key at any level, a value of the wrong form, or a TOML syntax error is
  `PKG-MANIFEST-INVALID`. A `tool` or `tool.NAME` that is not a table is also
  `PKG-MANIFEST-INVALID`. `name` is optional and follows the rule of a
  dependency name below. `max_line_width` is an integer of 1 or more.
  `blank_line_after_end` is a boolean, false by default; any other value is
  `PKG-MANIFEST-INVALID` at `style.blank_line_after_end`.
- `agentica = "0.31.0"` (optional) is the oldest Agentica the project or package
  works with: one SemVer version, read as a minimum, in the order of semver.org
  §11 (`0.31.0-alpha.2 < 0.31.0-alpha.10 < 0.31.0-beta.1 < 0.31.0`; build
  metadata `+...` is ignored). Anything else, a range included, is
  `PKG-MANIFEST-INVALID` at `agentica`. `install`, `check`, `run`, `test` and
  every command that loads the project check the key of the project and of each
  locked package against the running version, and `add` and `update` that of
  each package they resolve; a newer one is `PKG-AGENTICA-TOO-OLD` at `agentica`
  of that manifest. A member of a workspace (below) also checks the key of the
  workspace root's manifest, before the root's other keys. The key is read and
  checked right after the TOML parse, before any other key and before the lock,
  so a manifest written for a newer Agentica reports the version it needs rather
  than a key this one does not know. `run -- FILE.agcb`, `fmt` and `lint` do not
  check it. The running version is the `VERSION` file as written when the binary
  was built, so a build of master between releases reports the last release.
- With `max_line_width = N`, `agentica check` and every command that checks a
  program report a line of more than N characters (Unicode code points; a CR
  before the line feed does not count; comments count) as
  `CHECK-LINE-TOO-LONG`, from its first character past N to its end, after the
  type check passes. It covers the same files as `blank_line_after_end`
  (below), and in a file it comes before that rule. `agentica fmt` lays out in
  N columns (119 without the key) and, with `blank_line_after_end`, adds the
  empty lines that rule asks for.
- With `blank_line_after_end = true`, `agentica check` and every command that
  checks a program require an empty line (only spaces or tabs) after each line
  whose code is only `end`, in the files below the folder of that manifest
  that have no `agentica.toml` of their own nearer. A file outside that folder
  (`../shared/util.agc`), `std/`, a package, the `agc_libs/` of the folder, any
  other `pkg/` library folder (and what its files import by a relative path),
  and a file in a folder with its own manifest are not checked, even when the
  root imports them. A link counts where its real path is. The key of a nested
  manifest is not honored: a build reads only the manifest of its root. A
  trailing `# comment` on the `end` line is allowed, but a comment line after
  the `end` is not an empty line, so it needs one too, also before a closing
  `end` and at the end of the file. A line that breaks it is
  `CHECK-BLANK-LINE-AFTER-END`, at the `end`, reported after the type check
  passes. A line that starts with `end`, `else`, `elsif`, `)`, `]` or `}`
  needs no empty line before it. The end of the file needs none either: the
  last `end` may have no final line break, one, or extra empty lines, in a
  module file and in the main file. An `end` with more on its line (`end)`,
  `end + xs`) is not covered, and an `end` in a string, a heredoc or a comment
  never counts.
- A dependency is a local name and an inline table. The name is the key: a
  lowercase letter, then lowercase letters, digits, `_` and `-`, at most 64
  characters. It is the segment after `pkg/` in an import and has nothing to do
  with the URL, so moving a repository changes only its `git` line. The table
  has `git`, an `https://host/owner/repo` URL (an optional `.git` at the end; a
  lowercase host with no port and no user name; exactly an owner and a
  repository, each with only letters, digits, `.`, `_` and `-`, not `.`, `..` or
  starting with `-`, not ending in `.` and not a Windows device name such as
  `con` or `nul`), and exactly one of `tag` (1 to 128 letters, digits and the
  characters `.`, `_`, `+` and `-`; no `/`, and not starting with `.` or `-`) or
  `ref` (7 to 64 lowercase hex digits of a commit), and optionally `subdir`
  (next item), or a `path` instead of all of those (the item after the next).
  A branch, a version range or another key is `PKG-MANIFEST-INVALID`, at the
  key path (`dependencies.sqlite.branch`). `override = true` and
  `group = "test"` are the only other keys (their items below).
- `subdir` says that the package is a folder of the repository, not the
  repository itself, so one repository can hold many packages. It is a relative
  path of plain folder names joined by `/` (`"postgres"`, `"libs/sql"`). Each
  name has only letters, digits, `.`, `_` and `-`, and is not empty, hidden (so
  no `.` or `..`), `agc_libs` (in any case), ending in `.` or a Windows device
  name such as `con`; the whole path has at most 128 characters. Anything else,
  a leading or final `/` and a value that is not text included, is
  `PKG-MANIFEST-INVALID` at `dependencies.<name>.subdir`. The folder is the
  package: its files are the files of the package, its own `agentica.toml` is
  the manifest of the package, and relative imports cannot leave it
  (`CHECK-IMPORT-PATH`), as they cannot leave the repository of a package
  without `subdir`. A project installs only the folders it declares. A package
  that needs another folder of its own repository declares it like any other
  dependency (the same `git`, its own `subdir` and pin). Versions use prefixed
  tags (`postgres-0.1.0`).
- `path = "../sqlite"` is a dependency on a folder of this machine: relative to
  the folder of the manifest, or absolute; not empty, with no control
  character, at most 1024 characters. It excludes `git`, `tag`, `ref` and
  `subdir` (`PKG-MANIFEST-INVALID` at `dependencies.<name>`), and the
  folder must hold an `agentica.toml` (else `PKG-MANIFEST-INVALID` at
  `dependencies.<name>.path`, as for a workspace member). Like a workspace
  member it is neither fetched, cached nor copied to `deps/`: the build reads
  the files from the folder, with no hash check, so an edit there is seen by
  the next build, and the `agentica.toml` of the folder declares its
  dependencies as for any package. Its lock entry has `name` and `path` as
  written, and no `git`, `commit` or `hash` (any of them is `PKG-LOCK-INVALID`).
  Its answer is `in place NAME@path` from `install` and `added NAME@path` from
  `add` and `update`. A package can be published, so a `path` is allowed only in
  the manifest of the root project: in the manifest of a package (fetched, or a
  workspace member) it is `PKG-ROOT-ONLY` at `dependencies.<name>.path`.
- `override = true` in a dependency of the root manifest makes its source win
  for that name everywhere in the tree, with any of the sources above (a `path`
  too, to try a local copy of a transitive dependency). A package that asks for
  another source of the name is not a `PKG-SOURCE-CONFLICT`, and the source it
  asks for is never fetched or compared; the files of the name are the root's,
  for the project and for every package. Only the root manifest may say it: in
  the manifest of a package it is `PKG-ROOT-ONLY` at
  `dependencies.<name>.override`, and `false` is the same as leaving it out. The
  lock entry has `override = true` after its other keys; the root manifest and
  the lock must agree (`PKG-LOCK-STALE` at the manifest), and the lock key must
  be `true` (else `PKG-LOCK-INVALID` at `package[n].override`). `install`,
  `add` and `update` end their answer with one line for each overridden
  package, `overridden NAME@VERSION`, and `add` and `update` add
  `(another source asked by A, B)` when packages asked for another source.
  `PKG-SOURCE-CONFLICT` has a help that suggests `override = true` in the
  root manifest.
- `group = "test"` (Bundler's `group: :test`) puts a dependency in the test
  group: only the tests of the project import it. `test` is the only group; any
  other value is `PKG-MANIFEST-INVALID` at `dependencies.<name>.group`. The
  project locks, fetches and installs its test group like any dependency, with
  the same lock entry (no key says the group). Only a test build imports it:
  the `*_test.agc` files and the step program that `agentica test` compiles,
  with the files they import. `agentica check`, the queries (`type-at`, `refs`)
  and `std/analysis` decide by the name of the file: a `*_test.agc` file or a
  `steps.agc`, so a step program given as `agentica test --steps other.agc` is
  a test only under `agentica test`. In any other build an import of it from a
  file of the project is `CHECK-IMPORT-PACKAGE` at the import. The test group
  of a package is its own: a project that depends on the package does not
  resolve, fetch or lock it, does not check it against its lock, and the files
  of the package cannot import it (`CHECK-IMPORT-PACKAGE`). A name of the test
  group that another package needs is one source in the build, as for any
  name.
- A repository of packages can be a workspace, like an npm workspace. Its root
  `agentica.toml` has a `[workspace]` table with `repository`, the `git` URL of
  the repository (the rules of a dependency's `git`), and `members`, a
  non-empty list of the folders of its packages. A member is written like a
  `subdir`, appears once, and holds its own `agentica.toml`. An unknown key, a
  missing key, a bad value or a member that fails these rules is
  `PKG-MANIFEST-INVALID` at `workspace.repository`, `workspace.members` or
  `workspace.members[n]`.
- A project is in a workspace when its folder (the folder of its nearest
  manifest) is the root of the workspace or a member. The root is the nearest
  `agentica.toml`, going up from the project folder, that has a `[workspace]`
  table. The project is in it when its folder is that root, or its path from
  the root is one of the `members`; only then is the table checked in full. A
  table that does not list the project, even a broken one, is the same as no
  table for it (a project that is the root itself reports a broken table). The
  search stops at the root of the file system, and a project whose folder is
  directly inside a folder named `deps` is a package of `deps/` and is never in
  a workspace. A manifest above the project that cannot be read or parsed is
  skipped. The `[workspace]` table of a package that is in the cache
  or in `deps/` is never read, so it is not checked.
- In a workspace, a dependency whose `git` is the `repository` (with or without
  a `.git` at the end) and whose `subdir` is a member is a workspace member,
  wherever the manifest that declares it is: the project's own or a package's.
  It keeps its `git`, `tag` or `ref` and `subdir` in the manifest, which is what
  a user outside the repository resolves, but it is neither fetched nor copied
  to `deps/`: the build reads its files from the member's folder, with no hash
  check, so an edit there is seen by the next build. The folder's own
  `agentica.toml` declares its dependencies as for any package, and its files
  keep the rules of a package (relative imports stay inside the folder). The
  lock entry of a member has `workspace = true` in place of `commit` and
  `hash`, and needs `subdir`; a `commit` or a `hash` with it, a `workspace`
  that is not `true` or a missing `subdir` is `PKG-LOCK-INVALID`. The lock must
  say the same as the workspace: a member locked as a fetched package, or a
  package locked as a member for a project that is not in the workspace, is
  `PKG-LOCK-STALE` at the project's manifest and `PKG-SOURCE-CONFLICT` at a
  package's. `install`, `add` and `update` remove a `deps/` folder that has
  the name of a member. Outside the repository nothing changes: the same
  dependency is fetched and locked with a commit and a hash.
- The import is `pkg/<name>/<module path>`, with no extension:
  `"pkg/sqlite/util/json"` loads `util/json.agc` of the package. `pkg/sqlite`
  with no module is `CHECK-IMPORT-PATH`. A name that the manifest of the
  importing file declares is a package, and it comes first: it shadows a library
  of the same name in the `pkg/` roots, `agc_libs/` included. Its files come
  only from `deps/<name>/` beside `agentica.toml`, one flat folder for each
  locked package, including the ones that packages import (the lock is one list,
  so one folder for each name). A name that is not declared is the `pkg/`
  library search above, unchanged. Since the prefix is `pkg/`, a package import
  never clashes with a local file or folder.
- Which manifest decides: the manifest of the project for the files of the
  project (and of the `pkg/` libraries it loads), the manifest of the package
  itself, read from its folder in `deps/`, for the files of a package. A
  package file imports only the packages its own manifest declares; a `pkg/`
  name it did not declare is `CHECK-IMPORT-PACKAGE`, and the project cannot
  import the dependencies of a package unless it declares them too. A package
  file imports its own modules by relative paths that stay inside the package: a
  `../` that leaves it, a hidden folder, `_build/`, `agc_libs/` or `deps/` of
  the package, are `CHECK-IMPORT-PATH`.
- A manifest that declares a dependency needs `agentica.lock` beside it
  (`PKG-LOCK-MISSING`). Only the lock of the project is read; the
  `agentica.lock` of a package never is. The lock is TOML: `version = 1` (a
  missing `version` or any other value is `PKG-LOCK-INVALID`), then one
  `[[package]]` for every package of the build, direct or not, one entry for
  each name (a name twice is `PKG-LOCK-INVALID`): `name`, `git`, `subdir` (only
  when the dependency has one), `tag` or `ref` (as in the manifest), `commit`
  (40 or 64 lowercase hex digits; it starts with the `ref`) and `hash`
  (`sha256:` and 64 lowercase hex digits), `workspace = true` for a member
  of the workspace of the project, or `path` in place of the git source for a
  `path` dependency, then `override = true` for an overridden name. A bad lock
  is `PKG-LOCK-INVALID`, a bad `subdir` too, at `package[n].subdir`. Every
  dependency of the manifest must be
  in the lock with the same `git` (with or without a `.git` at the end), the
  same `subdir` (or none) and the same `tag` or `ref`, or the same `path`, and
  the same `override`, or the lock is `PKG-LOCK-STALE`. The same check runs
  on the manifest of every locked package that is in `deps/`: a name the lock
  lacks is `PKG-LOCK-STALE`, and a name with another source than the lock is
  `PKG-SOURCE-CONFLICT`; both are reported at `dependencies.<name>` of that
  manifest. One name with two different sources anywhere in the
  tree (the project and a package, or two packages) is `PKG-SOURCE-CONFLICT`,
  unless the project overrides the name (the item on `override`);
  the source is the `git`, the `subdir` and the pin; there are no versions to
  compare and no ranges to solve. Both checks run once for every command that
  loads code, before any file is read, so a conflict is reported whether or not
  an import reaches that package. A package that is not in `deps/`, one whose
  folder cannot be listed and one whose manifest is not a regular file are left
  for the import that loads them (so a conflict in them shows only then). A
  manifest that is a symbolic link, a folder or a pipe is `PKG-SYMLINK` and is
  never opened. The build never writes the lock.
- Manifest and lock errors have no source span. They name the file and the key
  path, such as `dependencies.sqlite.git` or `package[1].hash` (`[n]` counts
  from 0); a TOML syntax error has the line and column instead. In the plain
  form the key path replaces the source lines (`= key: ...`); in `--ai` it is
  the `key:` line; in `--json` it is `key_path`, and `range` is the start of the
  file. A failure about the file as a whole (a lock that is missing, a file that
  cannot be read) has no key: the plain and `--ai` forms show the file name
  alone, and `--json` has no `key_path` and a `range` at line 0, column 0.
- The package cache is a download cache, so that a commit is never fetched
  twice; `install`, `add` and `update` fill it and write `deps/` from it. It
  holds one folder for each commit:
  `$XDG_CACHE_HOME/agentica/pkg/<host>/<owner>/<repo>/<commit>/`, from the `git`
  URL of the lock. Two names for one repository are two packages, each with its
  own lock entry. A package with a `subdir` has the folder `<commit>@<subdir>`
  instead, each `/` of the `subdir` written `@` (a `subdir` never holds one),
  and that folder holds only the files of the `subdir` folder. Two folders of
  one repository and commit are two cache folders, and a change in another
  folder of the repository changes neither. `XDG_CACHE_HOME` counts when it is
  absolute, else `~/.cache` is used (no cache when `HOME` is unset too). On
  Windows the folder is `%LOCALAPPDATA%/agentica/cache/pkg/` (no cache when it
  is unset or relative; `XDG_CACHE_HOME` and `HOME` are not read). A declared
  package that is not in `deps/` is `CHECK-IMPORT-PACKAGE`, whose help says to
  run `agentica install`.
- `agentica install` fills the cache from the lock, writes `deps/` (below) and
  never writes the lock. It
  takes no argument; the project is the nearest `agentica.toml` going up from
  the working folder (none is `PKG-MANIFEST-MISSING`), and the lock is checked
  against the manifest as a build checks it (`PKG-LOCK-STALE`). For each locked
  package, in the order of the file: a folder of the commit that is in the cache
  and has the locked hash is left alone and git does not run; a folder with
  another hash is `PKG-HASH-MISMATCH` and is never overwritten; else the package
  is fetched. The fetch runs the system `git` (its config, SSH keys and
  credential helpers apply; a `url.<base>.insteadOf` setting applies to the
  `git` value, which the lock keeps as written): a depth-1 fetch of the tag, or
  of the locked commit for a `ref`, into a temporary bare repository with no
  hooks and no working tree. The fetched commit must be the locked `commit`,
  else `PKG-TAG-MOVED`. The files are read from the commit tree with `git
  ls-tree` and `git cat-file`, so `.gitattributes` changes nothing. Only the
  files the hash covers and the `agentica.toml` at the root are copied. With a
  `subdir`, the tree read is that folder of the commit: the fetch is the same,
  but nothing outside the folder is listed, read or written; a `subdir` that the
  commit lacks, or that is a file, a symbolic link or a submodule there, is
  `PKG-FETCH` at `package[n].subdir`. A symbolic link or submodule named `*.agc`
  or `agentica.toml`, or in `native/`, is `PKG-SYMLINK`, two copied paths that
  differ only in case are `PKG-PATH-COLLISION` (only case: not Unicode
  normalisation or Windows device names, which the hash still catches), a file
  over 1 MiB, or all files over 16 MiB, is `PKG-FETCH` naming the file, and
  the hash of the copy must be the locked hash (`PKG-HASH-MISMATCH`). The copy
  is built in a hidden `.tmp-*` folder of the cache root and renamed into place
  in one step (a killed install may leave that folder; delete it). git may ask
  for a password on a terminal; each read of its output has a 5 minute
  deadline. A git that cannot start or fails, a missing tag or commit, an unsafe
  path and a cache that cannot be written are `PKG-FETCH`. These failures name
  `agentica.lock` and the key of the entry (`package[1].tag`,
  `package[1].hash`; `package[1].git` when git itself failed; `package[1]` for
  the others). The first failure stops the command. When every package is in
  the cache, the manifest of each is checked against the lock
  (`PKG-LOCK-STALE`, `PKG-SOURCE-CONFLICT`), and only then is `deps/` written,
  so a cache or a manifest that fails those checks writes nothing there. A
  failure in the middle of the copy (a full disk, say) leaves `deps/` partly
  updated: each package folder is either the old one or the new one, and
  `agentica install` finishes the rest. The
  answer is `fetched NAME@VERSION`, `in the cache NAME@VERSION`, for a
  workspace member `in the workspace NAME@workspace` or, for a `path`,
  `in place NAME@path` for each package, then `overridden NAME@VERSION` for
  each overridden package; with no package but host artifacts ready,
  `1 native artifact ready` (or `N native artifacts ready`); else `nothing to
  install`. The command starts git even under `--deny-run`, which only limits
  programs.
- `agentica add NAME URL --tag TAG` (or `--ref COMMIT`, `--subdir DIR` and
  `--group test`) and
  `agentica update [NAME]` write the lock; they are the only commands that do.
  Both work on the project of the working folder (no manifest is
  `PKG-MANIFEST-MISSING`), read the lock without checking it against the
  manifest, and fetch as `install` does (the same `git`, the same checks, the
  same cache), so they may start `git` and need the network for what is new. The
  lock they write has one entry for every package of the build and no other: the
  dependencies of the manifest, then those in the manifest of each package they
  settle, and so on; one name with two sources is `PKG-SOURCE-CONFLICT`, at the
  manifest that asked second. A locked entry with the source the manifest names
  is kept, and only its files are put in the cache if they are missing; anything
  else is fetched, and the commit and the hash are read from what git gave; a
  fetch error of such a pin names the manifest that asks for it and
  `dependencies.<name>.git` (or `.tag`, `.ref`, `.subdir`), the same codes as
  `install`. Nothing is written when a step before the lock fails, and the lock
  is written before the manifest and `deps/` after both: if `deps/` cannot be
  written, `agentica install` writes the locked packages into it (it removes
  no folder). A file that cannot
  be written is `PKG-WRITE`; each file is written to a new file beside it that
  is renamed into place, and the old one is put back if a step fails. A
  manifest that changed while the packages were fetched is not overwritten
  (`PKG-WRITE`, nothing written), and a manifest that cannot be written after
  the lock was says so in the help: `agentica update` makes the lock match it
  again. The lock is sorted by name (just `version = 1`
  when it is empty), in the layout above, so it has the same bytes when nothing
  changed.
  - `add` takes the local name, the `https://` URL and `--tag` or `--ref`, in
    that order, then `--subdir DIR` if the package is a folder of the repository
    and `--group test` for the test group. The commit of `--ref` is the whole id
    (40 or, for SHA-256, 64 digits), since git fetches no abbreviation (a
    package whose manifest asks for a part of an id that the lock lacks is
    `PKG-FETCH` at `dependencies.<name>.ref` of that manifest). The tag of a
    SHA-1 repository is fetched; a SHA-256 repository takes `--ref`. A name,
    URL, tag or commit that the manifest would refuse, or any other words, are a
    usage error (exit code 2). A name that is a dependency already is
    `PKG-DEPENDENCY-EXISTS`. The manifest gets one new line, `NAME = { git =
    "URL", tag = "TAG" }` (with `subdir = "DIR"` and then `group = "test"` last
    when asked), after the last entry of `[dependencies]` (or in a new
    `[dependencies]` table at the end of the file); no other byte changes, so
    comments, blank lines, the order of the keys and the line endings stay. The
    new text is read as a manifest before it is saved, and a layout the edit
    cannot handle (the table written as `dependencies = {}`, say) is
    `PKG-MANIFEST-EDIT`: write the line by hand.
  - `update` takes no word or the name of a dependency of the manifest (else
    `PKG-DEPENDENCY-UNKNOWN`). It fetches the tag pins again, all of them or
    the one named, and takes the commit they point to now, so a moved tag is
    the new commit and hash in the lock. A pin that is a commit is not fetched
    again. It also fixes a lock that is missing or stale (a manifest edited by
    hand) and drops the packages that nothing asks for any more. A project with
    no dependency and no lock gets none.
  - Both refresh `deps/` as `install` writes it, for every package of the new
    lock, and remove the folder of a package that the old lock had and the new
    one lacks. If `deps/` cannot be written, the lock is saved already and the
    help says to run `agentica install` to write the locked packages into
    `deps/`.
  - A workspace member is locked with no fetch, whether or not its tag exists,
    and its manifest is read from its folder; its version is `workspace`.
  - The answer lists `added NAME@VERSION`, `updated NAME@VERSION` (another
    commit or pin) and `removed NAME`, one per line, or `nothing to update`;
    a package with a `subdir` adds ` (folder DIR)` after `NAME@VERSION`. With
    `--json` a success prints `{"ok":true}`.
- `deps/` holds the files of each locked package that is not a workspace
  member, direct or not, in
  `deps/<name>/` beside `agentica.toml`, like `mix deps.get`: the files the hash
  covers and the `agentica.toml` of the package (for a `subdir`, of that folder
  only: the cache holds nothing else). `install`, `add` and `update` copy them
  from the cache into a hidden `.tmp-*` folder of `deps/`, hash the copy against
  the lock (`PKG-HASH-MISMATCH` at `package[n].hash`), and swap it for the old
  `deps/<name>/` in two renames, so the old folder stays if a step fails. The
  folder of a locked package is replaced when it is not a real folder (a link,
  say) or its `.agc` files differ from the lock (an edited, added or missing
  file), and running `install` again is how to restore it. A real folder whose
  `.agc` files have the locked hash is left as it is, so its files keep their
  times, and so do other files in it (a note, say). Hidden `.tmp-*` and `.old-*`
  entries of `deps/` left by a killed command are removed first when they are
  older than ten minutes (a younger one may belong to a command that is still
  running), judged by their own time and never through a link. The new folder
  has the ordinary mode (not the private one of the staging folder). A
  `PKG-WRITE` that could not put an old folder back names the `.old-*` folder
  that holds it; `install` writes the package again from the cache, and the next
  command removes that folder once it is older than ten minutes. A folder of a
  package that `update` or `add` dropped from the lock is moved aside and
  removed without following links (a link is removed as a link). Nothing else in
  `deps/` is touched, and the tool writes no `.gitignore` there: a project may
  commit `deps/` or ignore it. `deps/` itself must be a real folder: a symbolic
  link is `PKG-SYMLINK`, and a file or a write that fails is `PKG-WRITE` (the
  file and no key); nothing is written through a link. `agc_libs/` is not
  touched: it stays for the libraries of the `pkg/` search. When `agentica
  test`, `check`, `fmt`, `lint` and `symbol` walk a folder, they skip the
  `deps/` beside an `agentica.toml` (installed packages are not the tests or
  modules of the project; a path that names a folder of `deps/` reads it) and
  `_build/` at any depth, where agentica writes its caches. These two names are
  exact.
- A build reads `deps/<name>/` of a declared name and hashes it against the
  lock: one that differs (an edited file, an added `.agc` file, a missing one)
  is `PKG-HASH-MISMATCH` at the import, and nothing else is used instead; a
  folder that is not there, or an entry that is not a folder, is
  `CHECK-IMPORT-PACKAGE`. The stored names of the files do not depend on where
  they were read. A link to a folder at `deps/<name>` is followed when a build
  reads it (the hash covers what is behind it); `install` replaces the link
  itself. A name the project does not declare is the `pkg/` library search.
- The hash covers the `.agc` files of the package folder and every file of its
  `native/` folder at the root, but dotfiles, `Thumbs.db` and `desktop.ini`
  (for a `subdir`, that folder of the repository, so a change in another folder
  does not change it).
  Their paths are relative to it, written with `/`, in bytewise order; for each
  file, its path, a zero byte, its size in decimal, a zero byte and its bytes.
  The hash is `sha256:` and the SHA-256 of that stream in hex
  (`OpenSSL.Digest.sha256`).
  Hidden folders and `_build/` (any depth), `agc_libs/` and `deps/` at the
  root and files that are not `.agc` (outside `native/`) are left out (`.agc`,
  `agc_libs`, `_build`, `deps` and `native` are compared without regard to
  case, so `x.AGC` is hashed and `AGC_LIBS/` is left out on every system). The
  `agentica.toml` of a package is left out too, so it can only choose among the
  names of the lock, except when `native/` holds a file that is not `.agc` or
  the manifest has a top-level `[native]` table: it then decides which file is
  opened, so it is added to the stream with the path `agentica.toml`, and the
  hash of any other package is unchanged. The first
  time a build loads a package, it hashes the folder of `deps/` and compares
  the result with the lock (`PKG-HASH-MISMATCH`); a symbolic link named
  `*.agc`, a link named `native` at the root, or any link in `native/`, is
  `PKG-SYMLINK`, and a FIFO, socket or device named `*.agc` or in `native/`
  is `CHECK-IMPORT-IO`. A package that no import reaches is not hashed. A build
  changes nothing in `deps/`. The bytecode cache of `agentica FILE.agc` hashes
  only the files a program reads, so a new unused file in a `deps/` folder is
  caught by `check` or `--no-cache`, not by a cached run. A committed `deps/`
  needs no `install` to build.
- Native libraries. A package declares them in its own manifest, one table
  `[native.NAME]` for each library, where `NAME` follows the rule of a
  dependency name and is what `extern "NAME"` writes in the files of the
  package. Under it, one key for each system the library exists on: `linux`,
  `macos` or `windows` (any other key is `PKG-MANIFEST-INVALID`; a macOS file
  is a universal binary, and `linux` is any Linux the VM supports). Its value
  is an inline table with exactly one of `file`, a path in the `native/` folder
  of the package (plain folder names, as a `subdir`; the files of `native/` are
  copied and hashed with the package, so the lock covers all systems, and each
  is at most 1 MiB), `system`, a name for the system loader (no `/`, `\`
  or `:`; at most 128 characters) or an absolute path, or a list of them (1 to
  16), for a library the system has (`winsqlite3.dll`), or a download
  `{ url, sha256, member }` (an https URL, or http to 127.0.0.1 or [::1]; 64
  lowercase hex digits; a safe relative TAR or ZIP member): the archive is
  verified by its SHA-256 and the member is cached, pinned per system in
  `[[native-artifact]]` and fetched by `install` and `update` for the host
  only. Another key, both shapes or a half-written download are
  `PKG-MANIFEST-INVALID` at the key path (`native.sqlite3.linux.file`).
  ```toml
  [native.sqlite3]
  linux = { system = "libsqlite3.so.0" }
  macos = { system = "libsqlite3.dylib" }
  windows = { file = "native/windows/sqlite3.dll" }
  ```
  - In a file of the package, `extern "NAME"` with a `NAME` that its manifest
    declares means the entry of the running system, chosen when the file is
    compiled: a `file` becomes the absolute path of the file in
    `deps/<package>/`, which the VM opens as it opens any absolute library (no
    search, and `LD_LIBRARY_PATH` plays no part); a `system` entry stays as
    written. A `NAME` it does not declare stays as written. Nothing else in the
    program changes, and `--deny-native` and `--sandbox` refuse the program as
    for any `extern`.
  - A `system` list names candidates in order of preference, for a library
    that lives at different places on one system, such as Homebrew's on macOS:
    ```toml
    [native.libpq]
    macos = { system = ["libpq.5.dylib", "/opt/homebrew/lib/libpq.5.dylib"] }
    ```
    When the file is compiled, the first absolute path that is a file is
    chosen, else the first bare name, else the first path (the program then
    fails to open it, as `extern "/missing.so"` does). A macOS path such as
    `/usr/lib/libz.dylib` lives in the dyld shared cache, not on disk, so it
    does not count as existing: list it knowingly, before or after a path
    that does. The choice is the
    machine's: the manifest is hashed as written, the lock holds no choice,
    and the bytecode cache misses when a candidate appears or goes away. A
    relative path (`lib/x.so`, `C:x.dll`), an empty list or an item that is
    not a string is `PKG-MANIFEST-INVALID` at the key path of the item
    (`native.libpq.macos.system[1]`). The working directory is never searched.
  - A package that declares the library but has no entry for the running
    system is `PKG-NATIVE-PLATFORM`, and a `file` that the package lacks is
    `PKG-NATIVE-MISSING`, when a file of the package that is compiled uses
    that `NAME`. Both name the `agentica.toml` of the package and the key path
    (`native.NAME`, `native.NAME.linux.file`), so a package works on the
    systems it names and is refused only where it is used on another.
  - A library that is a `file` is checked by the hash of the package when the
    package is first loaded, so a changed file is `PKG-HASH-MISMATCH`. The
    entry of the bytecode cache of `agentica FILE.agc` also holds the digest of
    the manifest and of every file of `native/` (a library may load a sibling),
    so a change to one is a cache miss and the build runs again. The bytecode
    that `agentica compile` writes names the file by its path on this machine,
    and `agentica run -- file.agcb` opens whatever is at that path, with no
    hash check.
  - The manifest of the project has the same `[native]` table, used by the
    project's own files, with the files relative to the project folder (a
    package author's tests run with the package as the project). The project's
    files are not hashed. A workspace member is read from its folder with no
    hash, as its `.agc` files are.
  - `build` and `optional` are the keys of `[native.NAME]` that are not a
    system. `build` gives the C sources of a native module (`extern module`),
    which the project, a workspace member, a `path` dependency and a fetched
    package build instead of using their system entry. A fetched package is
    never compiled in
    `deps/`: when a file first uses the library, the files its hash covers are
    read once and checked against the hash of its lock row
    (`PKG-HASH-MISMATCH` at `native.NAME.build`), and the files of `native/`
    among them are copied into a private build folder and compiled there. So
    the code that is built is the code of the locked commit: a file the hash
    leaves out (a dotfile, `Thumbs.db`) is not copied, and a header outside
    `native/` is not found. `check` never builds, but a copy that differs
    from the lock is still `PKG-HASH-MISMATCH` when the package is loaded.
    ```toml
    [native.stats]
    build = { sources = ["native/stats.c"], defines = ["NDEBUG"], libs = ["m"] }
    ```
    `sources` (1 to 256) are `.c` files in `native/`, as a `file` is;
    `defines` (at most 64) are `NAME` or `NAME=VALUE`, a C name and a value of
    letters, digits and `_ . + -`; `libs` (at most 32) are names for `-l`, of
    the same letters, not starting with `-`. Anything else is
    `PKG-MANIFEST-INVALID` at the key path of the item
    (`native.stats.build.defines[0]`), and so is a Windows device name (`con`,
    `nul`, `com1`) as the name of a library to build (at `native.NAME`). A
    source that is not a regular file of `native/` is `PKG-NATIVE-MISSING` at
    its item. For a package read in place, every entry of `native/` is read,
    hidden ones included, when a file first uses the library; a `native` that
    is not a folder, a link, a pipe or a device in it, or more than 4096 files
    or 1024 folders, is `PKG-NATIVE-BUILD` at `native.NAME.build`. A fetched
    package reads only the files its hash covers, within the limits of a
    fetch (1 MiB a file, 16 MiB in all; more is `PKG-NATIVE-BUILD` there), so
    its hidden files are in neither the copy nor the key.
  - A run, `compile`, `test` and `install` run the user's C compiler on the
    C of `native/`; `check` and the queries never do. Under any
    `--deny-*` flag or `--sandbox`, in front of `test` or after it, the VM
    refuses native code, so no compiler starts: a run or a test file that
    uses the library is `RUNTIME-NATIVE-DENIED` (the bytecode cache keeps
    such programs apart, so a hit and a miss agree), and `compile`, whose
    output may run without the flag, is `PKG-NATIVE-BUILD`. A run, `compile`
    and `test` build a library when a file of the program first uses it, so
    a library that no file uses is never built; `install` builds them all
    for the project, its members and its `path` dependencies, and none of a
    fetched package, so installing one needs no C compiler.
    The compiler is the words of `CC` (split at spaces, with no quoting), else
    `cc` (`gcc` on Windows), started with an argument list and no shell, in
    the package folder. Every build gets `-std=c11 -O2 -fvisibility=hidden`,
    the folder of the `agentica_native.h` that the binary carries, the defines
    (`-DNAME=VALUE`, one argument each) and the system's flags: Linux
    `-fPIC -shared -Wl,-z,defs`, macOS `-dynamiclib` with the install name
    `@rpath/libNAME.dylib` (the host architecture only; an undefined symbol
    is a link error there by default), Windows `-shared -static-libgcc`; then
    the sources and the `-l` libraries. The manifest names no compiler and no
    other flag.
  - The library goes to `<package cache>/native-build/<key>/libNAME.so`
    (`.dylib`, `NAME.dll`), never into the package. The key is the SHA-256 of
    the files of `native/`, the table, the compiler words, the first lines of
    its `--version` and `-dumpmachine`, the header, and `CPATH`,
    `C_INCLUDE_PATH`, `CPLUS_INCLUDE_PATH` and `LIBRARY_PATH`. Headers of your
    own must live under `native/`: system headers, installed libraries and
    the rest of the environment are not part of the key, so to build again
    after they change, remove the entry or change a file under `native/`. The
    files of `native/` are hashed again after the compile, and a change during
    it stores nothing (`PKG-NATIVE-BUILD`). The entry is made in a private
    folder and renamed into place with its receipt (the SHA-256 of the
    library); an entry or a `native-build` folder that is not private to the
    user, or a library that is not the one its receipt names, is
    `PKG-NATIVE-BUILD`, and so is a compiler that cannot start, fails or makes
    no library. Its standard error is printed as it is (the start of it in the
    message with `--json` and `--ai`), and a new build prints
    `built native NAME: PATH` on stderr. The bytecode cache of
    `agentica FILE.agc` watches, for each package that builds, every file of
    `native/` and its names (hidden ones too), the built libraries, `CC` and
    the four search variables, so an edit or a new file in `native/` builds
    again. A compiler replaced at the same path is seen only when the program
    is compiled again.
  - `optional = true` beside `build` makes the module optional: when the
    build fails (no compiler, a compile error, an unusable build cache), a
    run, `compile`, `test` and `install` go on without it, after the warning
    `PKG-NATIVE-UNBUILT` at `native.NAME.build` on stderr, once a run: the
    line `warning: native module NAME not built: REASON; the package runs
    without it`, with `--json` the object of the problem with
    `"warning": true`, with `--ai` its block with `warning` as the first line.
    `Native.load("NAME")` then gives `error` and a call of the module is
    `RUNTIME-NATIVE-LOAD`. The bytecode cache stores no program whose module
    block names it, so every run compiles the program again and tries the
    build again, with its warning; a program that `compile` wrote without
    it never opens it. A missing source,
    a link in `native/`, a copy that differs from the lock and the `--deny-*`
    flags fail as for a required module. `optional` without `build`, or not
    a boolean, is `PKG-MANIFEST-INVALID` at `native.NAME.optional`.
- The stored name of a package file in the `.agcb` file is
  `pkg/<name>@<tag>/path/in/package.agc`, such as `pkg/sqlite@v1.2.0/db.agc`
  (the path is from the package folder, without the `subdir`); for a package
  pinned by a `ref` it is `pkg/<name>@<first 12 digits of the commit>/...`. So
  the bytes do not depend on the folder of the project. Diagnostics inside a
  package name the real file in `deps/`.

**Decided against (packages).**

- Semver and a major-version rule, and a `v2` path segment (it clashes with
  folders in the repository): one name has one source, and two majors can be
  used under two names.
- `dev_dependencies`: there is one list of dependencies.
- `owner/repo/mod` as the import form (it clashes with local folders and needs
  an ambiguity rule) and `./` for relative imports: the form is
  `pkg/<name>/<module>`.
- Hashing only at install: every build hashes each package it loads, so a
  changed file of `deps/` is caught.
- A `files` list in the manifest: only `.agc` files and the files of `native/`
  are used and hashed.
- A `JSON.Value` value or typed decoding for `Toml.parse`: the result is the
  enum `Toml.Value`, which keeps the types of TOML and works with `case`.
