# SOLONCODE: start here

SOLONCODE is a bounded typed dataflow language. `.solon` defines pure `fn`, explicit `effect fn` and one `solonsky` module. Hosts run issued programs; supported pure code exports JavaScript/Python.

Read one brief. `/metadata.json` pins the legacy snapshot; `/release57.json` indexes compiled profiles.

## Run the existing pure example

From a 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
```

Input `{"approval":"unknown","xs":[-1,12,10]}` yields total44, ready unknown and status`"waiting"`. This example uses no adapters, models, network or persistent store.

## Pick one task

- Known builtin: `/brief/builtin/len.json` or `/brief/builtin/choose.json`; [pure example](../llm/examples/truth-flow.solon).
- Finite business logic: [profile](../core-stdlib-tools-completion.md). 24pure builtins/43stages; host library is separate.
- Known stage: `/brief/stage/match.json` for explicit results; `/brief/stage/asSchema.json` for typed Records; [all stages](core.md). Nominal values stay internal.
- Float: `/brief/stage/parseFloat.json`.
- Bits: `/brief/stage/bitAnd.json`; six32-bit stages use old required Int. [Example](../../examples/int-bits/README.md).
- Project: [16-module app](core-application-integration.md) or [tool/service](project-tool-service-handoff.md).
- Source adapters: [effect fn set](effect-function-set.md); [two tools/service](effect-function-set-service-handoff.md).
- Known SDK: preserve the exact subpath, e.g. `/brief/sdk/agents/ollama-stream.json`; follow its example and [host contract](host.md).
- Memory: [selection](memory-series-selection.md), [retention](memory-retention-workload.md).
- Service: [context](service-live-context.md), [pause/resume](service-maintenance.md), [remote](remote-service.md), [hosted](cloud-service-host.md).
- Joined application: [memory, media, tools and durable service](platform-acceptance.md).

If the item is unknown, use [core](core.md), [host](host.md) or [catalog](catalog.json). Full cards `/core/builtin/NAME.json`, `/core/stage/NAME.json`, `/sdk/SUBPATH.json` and `/contract/SECTION.json` provide detail. Skip history for a named operation.

Brief references hash exact response bytes, including newline. Follow one captured snapshot; reject mismatches. JSON/SHA is not publisher authentication. SDK symbols are binding names, not inferred signatures. See [brief contract](brief-cards.md).

## Boundaries

- Exact `Int` within ±9007199254740991; finite binary64 `Float`; `Truth` yes/no/unknown with no Boolean/number coercion. Unknown or formatted Text`"yes"` grants no permission.
- Immutable values, acyclic pure helpers and bounded explicit effects. Locals/derives are eager; `choose` is lazy. Fuel, byte and collection bounds apply.
- Optional DATA absence is not an omitted input, caught error or retry policy. Explicit virtual Text/SHA sources only; no ambient file/network/code resolver or general unbounded loops.
- Execute with original issued Program/receipt/host handles. Copies, hashes and documentation create no capabilities or native approval.
- `use` grants nothing; effects:[] adapters remain external. Generic `execute` creates no automatic durable journal/approval workflow. Use the selected explicit host/profile.
- Preserve running/uncertain effects: no retry/fallback/reclaim, new key/alias/conversation or fresh-journal bypass. Unknown usage remains null, not zero.
- Source/runtime/config changes can refuse saved bindings. No implicit reset or migration. Host examples can invoke providers or create stores; read their contract before running.

Syntax: [grammar](../llm/grammar.ebnf). Smaller documentation is not proof of lower total LLM task cost or better quality.
- Media: [formats and integration](media-integration.md).
- Mac: [pure](native-macos.md), [project](native-project-macos.md), [tools](native-project-tools-macos.md). [Wasm](wasm-project.md).