# SOLONCODE: start here

Read this page first. Fetch only the topic you need. [Catalog (repository-only)](https://github.com/alexsolonsky/ailanguage/tree/81b9342c305aa777f4016b9f454b828381ff1148/docs/ai/catalog.json) records the current source/package/AST versions and exact public package paths; these are different versions. Missing or draft metadata is not a release certificate.

SOLONCODE is a bounded typed dataflow language for agents and applications. `.solon` contains pure functions and one `solonsky` module. A JavaScript host runs the issued program; pure programs can export standalone JavaScript/Python. Host services, models, tools and storage are explicit bindings.

## Run a verified pure example

From the repository or installed package root, Node22+:

```sh
node language/bin/soloncode.mjs check docs/llm/examples/truth-flow.solon
node language/bin/soloncode.mjs run docs/llm/examples/truth-flow.solon --inputs docs/llm/examples/truth-inputs.json
```

The existing input is `{"approval":"unknown","xs":[-1,12,10]}`. Outputs: total44, ready unknown, status`"waiting"`. This example uses no adapters, model, network, persistent store or paid service.

```js
import {readFile} from 'node:fs/promises';
import {compileModule, execute} from 'soloncode';
const source = await readFile('docs/llm/examples/truth-flow.solon', 'utf8');
const program = compileModule(source);
const receipt = await execute(program, {approval:'unknown', xs:[-1,12,10]});
console.log(receipt.outputs);
```

## Choose one route

| Task | Read |
| --- | --- |
| Write `.solon`, types, operations, limits | [core.md](/docs/ai/core.md) |
| Models/tools/MCP, storage, service, dialogue, API/media | [host.md](/docs/ai/host.md) |
| Find an exact import path and its canonical contract | [catalog.json (repository-only)](https://github.com/alexsolonsky/ailanguage/tree/81b9342c305aa777f4016b9f454b828381ff1148/docs/ai/catalog.json) |
| Exact grammar | [grammar.ebnf](/docs/llm/grammar.ebnf) |
| Edit original project sources | [project edits](/docs/project-edits-v0412.md) |
| Deliver fresh context or authenticated deltas | [context contract (repository-only)](https://github.com/alexsolonsky/ailanguage/tree/81b9342c305aa777f4016b9f454b828381ff1148/docs/context-delta-v03.md) |

On the documentation server, fetch a named card directly: `/core/builtin/len.json`, `/core/stage/fold.json`, `/sdk/root.json` or `/contract/types.json`. Replace the builtin/stage/section name for your task. Each card pins its versions. The complete catalog is optional; do not load it just to use a known core operation.

## Rules that affect every program

- `Int` is exact within ±9007199254740991. `Float` is finite binary64. `Truth` is yes/no/unknown; there is no Boolean or number coercion. Unknown never authorizes work.
- Values are immutable. Functions are pure and acyclic. Locals and derives execute eagerly; `choose` selects one branch. Operations have fuel, byte and collection limits.
- Imports use explicit virtual source/Text/SHA snapshots. No ambient file/network/code resolver, arbitrary evaluation, general unbounded loops or arbitrary native backend.
- Use actual compiler-issued Program/receipt/host handles. JSON copies, source hashes and formatted words are data, not execution or approval authority.
- `use` grants no capability. Model/tool requests need explicit host registration and applicable approval. Never retry/reclaim an uncertain external action, change its key, create a fresh journal or erase its unknown cost.
- A source edit or model/config change can invalidate an existing execution/storage binding. Do not migrate or reset saved data implicitly.

For semantics, read the selected canonical contract and matching implementation/tests. For a current implementation change, repository AGENTS.md and LLM-START.md remain the development instructions. This entry is a usage map, not historical benchmark evidence or a claim of lower total LLM cost.