git:20261006.d204621 to git:20261007.6e63371

# 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.

```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`, `?`),

- Named and default arguments: `fn volume(width: i64, height: i64 = 2)`

then `volume(2)`, `volume(width: 2, height: 3)`, or `volume(2, height: 3)`.

- 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

- 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 descriptor, e.g. `fs::File::fd()` of

`/dev/tty` when stdin is piped), `os::fd` (`wait_readable`), `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.