llms-full.txt git:20261008.a3bc32dA

Immutable. This exact content never changes and is served at /api/v1/blob/39d10a825e9a1a04.

# Gossamer LLM Reference

Generated from `SKILL.md` and `docs_src/api/stdlib.json`. This is deliberately scoped: only catalog entries with a standalone executable example and explicit verified status may appear as API recommendations.

## Language primer

# Gossamer - Skill Card

Drop this file into a model's context to teach it idiomatic Gossamer. For
anything not covered here, ask the toolchain (section 2) instead of guessing.

## 1. What Gossamer is

A fast-compiling language with deterministic memory management (reference
counting, cycle collection, `arena { }` regions - no borrow checker, no
lifetimes, no GC pauses). Syntax is Rust-flavoured; the runtime is Go-shaped
(goroutines, channels). Files end in `.gos`, the toolchain is `gos`, and a
project carries a `project.toml`. Programs run on the bytecode VM and JIT
(`gos run`) and as native binaries (`gos build`), with the same output on
every tier; `gos feature-status` says which surface is settled.

## 2. Lean on the toolchain

- `gos mcp` (e.g. `claude mcp add gossamer -- gos mcp`) exposes `check`,
  `execute`, `build`, `test`, `fmt`, `doc`, `explain`, `lint`,
  `feature_status`, and navigation (`hover`, `definition`, `references`,
  `workspace_symbols`). `check`, `execute`, `fmt`, `doc`, and `lint` take an
  inline `source` string. Use `hover` for "what is this", `explain CODE` for
  any diagnostic, `doc` for a module's exports. This card is its
  `gossamer://skill-card` resource.
- Without MCP: `gos check FILE`, `gos run FILE`, `gos explain CODE`,
  `gos doc std::<module>`. `gos check --fix` applies the rewrites diagnostics
  carry.
- `gos check` is necessary, not sufficient: `gos run` proves semantics and
  `gos build` proves the native tier.

## 3. Cheat sheet

```gossamer
use std::io

const PI: f64 = 3.14159

struct Point { x: f64, y: f64 }
struct Pair(i64, i64)
enum Shape { Circle(f64), Rect { w: f64, h: f64 } }

trait Area { fn area(&self) -> f64 }

impl Area for Shape {
    fn area(&self) -> f64 {
        match self {
            Shape::Circle(r) => PI * r * r,
            Shape::Rect { w, h } => w * h,
        }
    }
}

fn sum(xs: [i64]) -> i64 {
    let mut acc = 0
    for n in xs { acc += n }
    acc
}

fn main() {
    let total = sum([1, 2, 3])
    let label = f"total: {total}"
    println(label)
    let area = Shape::Circle(2.0).area()
    println(f"a circle of radius 2 covers {area:.2}")
}
```

## 4. Not Rust: values, parameters, assignment

There is **no ownership transfer, no borrow checker, no lifetimes**. Reason
about values.

- **Every parameter is by value, and the caller is safe.** Passing a
  collection copies nothing a callee only reads, and the callee cannot change
  what the caller holds. A `mut` parameter writes the callee's own value.
  `&mut T` is the one form that writes back, and the call site spells it:
  `extend(&mut items)`. Pass `coll`, never `&coll`: a shared `&` parameter
  or argument is rejected (GP0054 / GP0055).
- **Assignment gives a value of its own**: after `let b = a`, `b.push(3)`
  leaves `a` alone. `clone()` is only for a second value from one you still
  write. Passing a value twice needs no clone.
- **A closure names its captures**: it reads their current values and its
  writes reach them, whatever the type (`xs.for_each(|x| count += x)`). No
  `move`. A spawned closure is the exception: it takes a snapshot of each
  capture at the spawn, and writing one inside it is GT0114 - answer the
  value through `join()`, a channel, or a `sync::Shared`.

```gossamer
fn tally(mut xs: Vec<i64>) -> i64 { xs.push(1); xs.len() }
fn extend(xs: &mut Vec<i64>) { xs.push(1) }

let mut items = #[1, 2]
tally(items)           // items is still #[1, 2]
extend(&mut items)     // items is now #[1, 2, 1]
```

| Rust habit | Gossamer |
|---|---|
| `vec![a, b]` | `#[a, b]` (`[a, b]` is a fixed array) |
| `HashMap::new()` + `insert` | `{"k": 1}` / `Map::new()` |
| `HashSet` | `#{a, b}` |
| `include!` / `#[path]` | a file IS a module - reach it with `use` |
| `"text".to_string()`, `&str` | a literal already is a `String`; there is one string type |
| `format!("{}", x)`, `println!` | `f"{x}"`, `println(..)` - no `!` on any call |
| `impl Display` to print | `{}` renders every type; `impl Display` only overrides |
| `let (a, b) = pair` | `let a, b = pair` |
| `x.wrapping_add(y)` | `x +% y` |
| `Rc<RefCell<_>>`, `move`, lifetimes | none: capture is automatic, RC is the memory model |

## 5. Writing it

**Names and imports**
- Import everything you name: `use std::{env, fs}` before `env::args()`;
  `use util::add` for a sibling file; `use intcode` before any `intcode::`
  path of a `[dependencies]` package (a `-` in its name becomes `_`). Always
  spell full std paths (`std::encoding::json`). Prelude types, collections,
  variants, and builtin calls need no import.
- Plain functions for free-standing logic; `impl` only when state belongs to
  a type. A function that answers a value declares `-> T` (GL0055).
- An `impl Trait for T` block holds the trait's items only (GT0072); one
  block per `(trait, type)`. A type has one method per name across all its
  impls (GT0096).

**Bindings and control flow**
- `let` by default, `let mut` near its one update site; `x += 1`, never
  `x = x + 1`. `if`, `match`, and `loop { break v }` are expressions.
- Destructure with plain lists: `let a, b = pair`, `let tx, rx = channel()`,
  `a, b = b, a` swaps. Parentheses only group nested patterns:
  `for (k, v) in m`, `let a, (b, c) = 1, (2, 3)`.
- `if let` / `while let`; let-chains `if let Some(x) = a && x > 0 { .. }`;
  `let Some(x) = opt else { return }` (the else must diverge).
- Exhaustive `match`, no `_ =>` unless every other case means the same.
  Labeled loops: `'outer: for .. { break 'outer }`.
- `defer expr` runs at every exit of its block (end, `return`, `break`, `?`),
  last first, and when a panic unwinds through it, so a deferred `unlock`
  or `close` runs in a panicking goroutine too.
- Named and default arguments: `fn volume(width: i64, height: i64 = 2)`
  then `volume(2)`, `volume(width: 2, height: 3)`, or `volume(2, height: 3)`.
- Semicolons only separate statements on one line. To continue an
  expression on the next line, end the line with its operator (`a &&` then
  `b`); `|>` is the one operator that may begin a line. A line starting
  with `&`, `*`, `-`, `|`, or `||` begins a new statement, so a closure on
  its own line is a closure (GP0067 when nothing reads it); any other
  operator there is GP0066, let-chain `&&` included.
- Delimited lists use commas on one line and newlines when multiline.

**Strings and formatting**
- `f"..."` interpolates any expression, with an optional spec after the
  first top-level `:`: `f"{name}"`, `f"{xs.len()} items"`,
  `f"{acct.balance * 1.1:.2}"`, `f"{m["k"]:>8}"`, `f"{n:x}"`, `f"{s:?}"`.
  `{{` / `}}` write braces; an expression with a `:` of its own goes in
  parentheses. Use it wherever values read in place, in prints and
  assignments alike.
- `format("{} of {}", xs.len(), total)` (and `println`, `print`,
  `eprintln`, `panic` with the same arguments) fills `{}` placeholders in
  order, or names a binding or field path (`"{total}"`); a template built
  once and filled from several places. Specs: `{:*>8}`, `{:08}`,
  `{:x}` `{:b}` `{:o}`, `{:.2}`, `{:+}`, `{:e}`; no positional `{0}`.
- `{}` renders any value, nested collections, structs, enums, and `Option`s
  included, each in the spelling that builds it (`#[1, 2]`, `{"a": 1}`,
  `Some("x")`, `P { n: 1 }`), the same on every tier. `{:?}` differs in two
  places only: it quotes a top-level `String` or `char` (`"hi"`, `'x'`),
  which shows empty strings and stray whitespace, and it shows the structure
  of a type whose `Display` is overridden. Write `{}` unless you need one of
  those. `impl Display for T { fn fmt(&self) -> String }` overrides `{}` and
  `to_string()`; `impl Debug for T { fn fmt }` overrides `{:?}`.
- `"""` strings dedent to their closing delimiter; `f"""..."""` interpolates.
- Two index spaces: `s.len()`, `s[i]` (a `char`), and `for c in s` count
  Unicode scalars; `s.byte_len()`, `s.byte_at(i)` (an `i64`), `s.bytes()`,
  `s.substring(a, b)` use byte offsets. Never mix them.
- `s.to_i64()` / `to_f64()` / `to_bool()` are strict parses answering an
  `Option`. `String + String` copies; build long text with `+=` on a
  `String::with_capacity(n)` or a `bytes::Builder`.

**Numbers**
- Bare literals (`0`, `1.5`); suffix only without context. `arr[i]` takes an
  `i64` - no `as usize`. Casts are checked: numeric to numeric, `bool`/`char`
  to int; narrowing masks (`300 as u8 == 44`), float to int saturates.
- `+ - *` panic on overflow on every tier and profile; `+%` `-%` `*%` (and
  `+%=`...) wrap at the declared width, and are the only way to wrap. Divide
  by zero panics, and so does a shift amount outside `0..BITS`; `<<%` /
  `>>%` take it modulo the width.
- Both operands of `+`, `<`, `==`, `&`, `a.min(b)`, `v.contains(x)` share one
  type: `u32 < i64` is GT0001, fixed with the cast that loses nothing
  (`a as i64 < b`; `gos check --fix` writes it). A literal must fit its
  operand's type (`u8 == 300` is GT0009); `-x` on an unsigned type is
  GT0001.
- Integers answer `checked_add`, `saturating_sub`, `overflowing_mul`, `pow`,
  `rem_euclid`, `signum`, `abs_diff`, `isqrt`, `count_ones`; a `char`
  answers `is_alphabetic`, `is_ascii_digit`, `to_digit(radix)`,
  `char::from_u32`; floats answer `mul_add` (one rounding). Limits: `i64::MAX`, `u8::MIN`, `f64::EPSILON`, `f64::NAN`.

**Types**
- `bool char i8..i64 u8..u64 isize usize f32 f64 String [T] [T; N] (A, B)
  Option<T> Result<T, E> &mut T`, user types, `Simd<T, N>`. No `i128`.
- Structs build by their declared shape: `Unit`, `Pair(a, b)`,
  `Point { x: 1, y: 2 }`. Structs, enums, tuples, and sequences compare and
  order structurally; `impl` of `eq` / `cmp` overrides. Recursive enums work
  directly: `enum List { Cons(i64, List), Nil }`. Two enums may share a
  variant name (`Conn::Ready`, `Job::Ready`); write `Enum::Variant` where a
  bare name would be ambiguous (GR0009).
- `#[derive(Debug, Default, PartialEq, Eq, PartialOrd, Ord)]`; `Clone`,
  `Hash`, `Copy`, `Display`, and serde are automatic, not derived.
  Conversions and operators are `impl From` / `TryFrom` / `Add` / `Mul` /
  `Index` ...; an operator takes one impl per right-hand type
  (`impl Mul<f64> for V2` beside `impl Mul for V2`).
- `type Id = i64` is transparent; `newtype UserId = i64` is a distinct type
  with its own methods, converted by `.into()`.
- Generics monomorphise: `fn f<T: A + B>(x: T)`, `where` clauses, generic
  structs, const generics `fn sum<const N: usize>(xs: [i64; N])`,
  associated types and consts, equality constraints `I: Iterator<Item = i64>`.
  No `dyn`, no blanket impls.
- Patterns: literals, ranges, or-patterns, `@` bindings, slices
  `[first, ..rest]`, guards.

## 6. Collections and iteration

- Literals: `#[1, 2]` Vec, `[1, 2]` fixed array, `{"k": 1}` Map, `#{1, 2}`
  Set; repeat forms `#[0; n]`, `[0; 4]`. `Queue`, `Stack`, `Deque`,
  `MinHeap`, `MaxHeap`, `BTreeMap`, `BTreeSet` build with `T::new()` /
  `T::from([..])`. Prefer the dedicated type for intent (`Stack` for LIFO,
  `MinHeap` instead of negated keys). One name each: `HashMap`, `VecDeque`,
  `BinaryHeap` are rejected.
- A parameter `[T]` takes an array, a `Vec`, or a view; `&mut [T]` writes
  through. `&mut xs[lo..hi]` is a window of `xs` (`fill(&mut px[2..6], 0)`),
  and `xs[1..4].sort()` sorts that part in place; a bare `xs[lo..hi]` is a
  copy. Only `Vec` resizes; `insert` / `remove` answer a `Result`.
- `for x in xs` over any collection - no `.iter()`, no `*x`. A `Result` or
  `Option` is not iterable: take the value first.
- Eager and lazy: `xs.map(f)` / `filter` on a sequence answers a `Vec`;
  `xs.iter()` answers a lazy `Iterator`, and ranges are iterators already:
  `(1..5).map(|i| i * i).sum()`. Adapters (`map filter take skip step_by
  enumerate rev zip chain flat_map filter_map take_while`) stay lazy;
  terminals (`collect sum count min max fold reduce any all find position
  join min_by_key`) end the chain. An adapter consumes its iterator - take a
  fresh `.iter()` per pipeline; `it.next()` advances in place. `collect()`
  into `Result<Vec<T>, E>` / `Option<Vec<T>>` stops at the first failure.
  `to_vec()` copies an array, slice, or set into a `Vec`.
- A type with `impl Iterator for T { type Item = X; fn next(&mut self) ->
  Option<X> }` works in `for` and gains the same adapters and terminals.
- Maps: any hashable value is a key; `m[k]` reads and writes, and so does a
  place below it (`m[k][i] = v`, `m[k].items.push(x)`, `f(&mut m[k])`);
  `m.inc(k)` counts; `m.or_insert(k, d)` fills; `m.iter()` walks pairs.
  `BTreeMap` / `BTreeSet` keep keys ordered and answer `first_key_value`,
  `pop_first`, and `range(lo..hi)`. A `Set`'s own order is unspecified: sort,
  or use `BTreeSet`, when order matters.
- Sorting: `xs.sort()`, `xs.sort_by_key(|p| p.score)` (`Reverse(k)` to
  descend), `sort_by` with a comparator answering a sign.
- Parallel twins of the eager walks: `par_map`, `par_filter`, `par_sum`,
  `par_reduce(identity, combine)`, with pure callbacks (GT0090 otherwise);
  answers do not depend on the machine. `img.par_chunks_mut(w, |row, px| ..)`
  writes disjoint chunks in place on every core.
- Callback shorthand: a std function names itself (`xs.map(math::abs)`);
  anything else is a closure (`people.map(|p| p.name)`).
- `DynValue` holds data whose shape arrives at run time (`kind()`,
  `at(i)`, `as_i64()`...). `Weak<T>` via `x.downgrade()` / `w.upgrade()`.

## 7. The `|>` forward-pipe

`|>` composes free functions, which have no receiver to chain from; methods
chain on their own (`s.trim().to_lowercase()`), and a chain may feed a pipe.
`x |> f` is `f(x)`. A step that takes other arguments is a closure whose
parameter is the slot the value fills: `x |> |v| f(a, v)` is `f(a, x)`.
There is no `$`.

```gossamer
let n = 3 |> double |> |v| add(10, v) |> |v| clamp(0, 100, v)
let shout = "  Hi  ".trim().to_lowercase() |> exclaim
```

## 8. Errors and panics

Fallible functions answer `Result<T, E>`; propagate with `?` (on `Option` in
an `Option` function; errors convert through `From`). Panic only for broken
invariants.

```gossamer
use std::{errors, fs}

fn load(path: String) -> Result<String, errors::Error> {
    fs::read_to_string(path).map_err(|e| errors::wrap(e, f"reading {path}"))
}
```

`errors::new(msg)` / `wrap(cause, msg)` / `is(err, needle)`; `{}` on an
error prints its whole chain, `.message()` the top. A panic ends its
goroutine; in `main` it exits 101. Recursion is bounded by memory, not a
frame count, and runaway recursion is `GX0008` on every tier.

## 9. Concurrency

Goroutines live inside a **`cohort { }`**, which joins every child on every
exit and answers `Result<(), errors::Error>` - the first failure (by spawn
order) cancels the rest. `spawn(f)` answers a `JoinHandle<T>`
(`join()` -> `Result<T, String>`) and must sit lexically in a `cohort { }`
in its own function (GT0086); `main` is the one exemption. Channels carry
values; `close()` ends a `while let Some(v) = rx.recv()` drain.

```gossamer
use std::errors
use std::sync::channel

fn gather() -> Result<(), errors::Error> {
    cohort {
        let a = spawn(|| fetch("one"))
        let b = spawn(|| fetch("two"))
        println(format("{} {}", a.join()??, b.join()??))
    }
}

fn main() {
    let tx, rx = channel()
    spawn(|| { tx.send(1); tx.send(2); tx.close() })
    let mut total = 0
    while let Some(v) = rx.recv() { total += v }
    println(f"total: {total}")
}
```

- Headers: `cohort(policy: Policy::CollectAll)` / `Policy::Race`,
  `timeout: ms`, `isolation: Isolation::Thread`, `on_error: OnError::Log`.
  Cancellation is cooperative: a cancelled `recv` answers `None`, `sleep`
  returns early, `defer` runs; long pure computation polls
  `runtime::cohort_cancelled()`.
- `select { v = rx.recv() => .., default => .. }` multiplexes;
  `time::after(Duration::from_millis(n))` is a timeout arm.
- `std::sync` has `Mutex`, `RwLock`, atomics, `WaitGroup`, `Once`;
  `sync::with_timeout(f, ms)`, `sync::shield(f)`. There is no OS-thread
  spawn API.
- Goroutines are cooperatively scheduled. They yield at channel, lock, and
  sleep operations, and compiled code also polls at the head of each loop
  nest; a nest that is counted all the way down and calls none of the
  program's functions runs to completion first.

## 10. Standard library

Discover signatures with `hover` / `gos doc std::<module>`. Areas:

- Core: `fmt io env fs path os process time context flag errors bytes
  bufio`. `process::run(prog, args)` executes without a shell;
  `Command::new(p).arg(a).stdout(Stdio::Piped).spawn()?` (after
  `use std::process::{Command, Stdio}`; also `env`, `dir`, `status`,
  `output`) answers a `Child` that reads, writes, and waits. `time::Instant`,
  `Duration`, `time::Time` (an instant with its UTC offset, RFC 3339).
  `fs::read_dir` entries carry `is_file`, `size`, `path` - do not re-query.
- Text: `strings strconv utf8 unicode regex`.
- Encoding: `json yaml toml xml csv base64 base32 hex pem binary`. Typed
  serde: `json::decode::<T>(text)?` / `json::encode(v)`, `from_json` /
  `to_json`, for structs and enums (externally tagged); fields take
  `#[rename("key")]`, `#[skip]`, `#[default]`. Untyped: `json::parse` +
  `get`/`at`/`as_i64`.
- Web: `net`, `http` (client `http::get`, server `http::serve(addr,
  handler)`, `http::router`), `http::websocket`, `html`, `mime`.
- Terminal: `term` (`is_terminal`, `size`, `enter_raw`, `read_input`,
  `resized`; each takes an optional `os::fd::Descriptor`: the `fs::File` of
  an opened `/dev/tty` when stdin is piped, kept open while the call uses
  it, or `term::STDIN` / `STDOUT` / `STDERR`), `os::fd` (`wait_readable`,
  same argument), `os::signal`
  (`on(signal::SIGWINCH)`; `n.wait()` answers false once its cohort is
  cancelled or `n.stop()` runs), `process::run_inherit` (hand the terminal
  to a child), `unicode::char_width` / `str_width`. Restore state with
  `runtime::at_exit(f)`.
- Also: `sort`, `math`, `crypto::{sha256, hmac, aead, ed25519, password,
  rand}`, `hash`, `uuid`, `jwt`, `compress`, `archive`, `metrics`, `slog`,
  `testing`, `runtime`, `pprof`, `database::sql` (drivers via bindings),
  `ffi` (C types and strings for foreign calls).

```gossamer
use std::http
use std::http::router

let r = router::Router::new()
    .get("/", handler_fn)
    .get("/ping", |_r| Ok(http::Response::text(200, "ok")))
http::serve("0.0.0.0:8080", r)?
```

## 11. Comptime, arenas, HTML

- `comptime { }` blocks, `comptime fn`, and `comptime` parameters run while
  compiling and fold to constants; `typeInfo::<T>()` reflects fields;
  `codegen(s)` splices generated source.
- `arena { }` bump-allocates an object graph freed at the block's exit;
  nothing inside may escape (GM0003).
- HTML lives in its own `.html` file, read at run time or embedded with a
  `comptime` read.

## 12. Testing

```gossamer
#[cfg(test)]
mod tests {
    #[test]
    fn add_adds() { assert_eq(super::add(2, 3), 5) }
}
```

`assert(cond[, msg])` / `assert_eq(a, b[, msg])`. A test that records no
assertion fails, unless it answers `Result` and reaches `Ok`. `gos test` also
runs fenced code in `//` doc comments.

## 13. Projects and the toolchain

```
project.toml    # [project] id/version/gossamer-version; [dependencies];
                # [registries] default; [rust-bindings]
src/main.gos    # binary entry (lib.gos for a library; dir/mod.gos = module)
tests/          # integration tests
```

- Versions: `x.y.z` pins, `^x.y.z` accepts it or later. The entry file may
  hold top-level statements instead of `fn main`.
- C functions through `unsafe extern "C" { fn strlen(s: [u8]) -> usize }`
  blocks, called inside `unsafe { }`; `type Handle` declares an opaque C
  type, reached as `ffi::Ptr<Handle>` (`Option<Ptr<..>>` where C may answer
  NULL). Parameters are scalars, pointers, out-parameters (`&mut i32`,
  `&mut Option<Ptr<T>>` for `T **`), callbacks `Fn(..) -> R` filled with a
  named `fn` (any thread may run one), `[T]` / `&mut [T]` of scalars or
  structs, `#[repr(C)]` structs and `ffi::Union<(A, B)>` by value (`&mut S`
  for `S *`); a struct is a result too. `static NAME: T` in the block is a C
  global, reached as `ffi::addr_of(NAME)`.
  Memory through a `Ptr` is copied inside `unsafe`: `ffi::read`, `write`,
  `read_at`, `read_bytes`, `read_cstr`, `alloc` / `free`. Callback context is
  an `ffi::Handle::new(value)` passed as `h.as_ptr()`; `ffi::fn_addr(f)`
  fills a function-pointer field, `ffi::View::new(p, n)` reads C memory in
  place. `gos bindgen --c lib.h` writes the declarations for a header.
- C the package carries goes under `[native] sources = [..]` (`include`,
  `defines`); declarations without `#[link]` reach it on every tier.
- `#[export]` / `#[export("sym")]` on a free `fn` makes a C symbol;
  `[lib] kind = ["staticlib", "cdylib"]` builds the archive, shared library,
  and `include/<name>.h` (which also declares `<name>_shutdown()`).
- `[features]` (`default`, `dep:x`, `x/feat`), `optional = true` and
  `features = [..]` on a dependency, `#[cfg(feature = "f")]` on items and
  `use`, `--features a,b` / `--no-default-features` on every command. `#[link(name = "z",
  search = "dir")]`, `#[link_name = "sym"]`, and `#[cfg]` per platform;
  `ffi::last_errno()` (C `errno`) and `ffi::last_os_error()` (`GetLastError`
  on Windows); `gos check --target TRIPLE` checks another platform's
  declarations. Native code is allowed by default; `ffi = false` under
  `[project]` refuses it, and GT0102 then lists every library and file
  that declares one.
- Rust crates through `[rust-bindings]` (`gos new ID --template binding`,
  `#[gos_module("name")]`).
- `gos run FILE [ARGS]`, `gos build [--release] [-g]`, `gos test`,
  `gos fmt`, `gos lint`, `gos doc`, `gos new/init/add/fetch/publish`,
  `gos keygen`, `gos registry serve`, `gos env`, `gos repl`
  (`%i name` documents a symbol). Native builds need LLVM 18-22.

## 14. When in doubt

Run it (section 2). Spec: `SPEC.md`. Examples: `examples/`, starting with
`hello_world.gos`, `function_piping.gos`, `concurrency.gos`.


## Verified API reference

No stdlib entry is eligible for this section yet. Consult the structured [`docs_src/api/stdlib.json`](docs_src/api/stdlib.json) catalog with `gos check`/`gos`; its entries are deliberately quarantined until their fixtures and tier evidence land.