Gossamer Engineering

Gossamer Engineering

Use this skill for the Gossamer programming language: a pre-1.0, general-purpose, statically typed language whose source files are .gos and whose unified tool is gos. A Gossamer project is a versioned distribution unit described by project.toml. project.lock records resolution metadata for the package sources it covers; it does not authenticate an untrusted checkout, hash live path dependencies, or cover Cargo and prebuilt inputs used by Rust bindings.

Gossamer combines Rust-flavoured enum, trait, generic, pattern-matching, Option, Result, and ? syntax with Go-shaped M:N (many goroutines on many OS threads) goroutines and typed channels. Its automatic memory model is reference counting (RC) with compiled-tier cycle collection and scoped arena {} allocation. It has a bytecode VM, optional in-process Cranelift JIT, and LLVM ahead-of-time (AOT) native builds.

This is not the unrelated ChainSafe Go project named Gossamer. Do not load this skill for Polkadot/Substrate work, Go packages, or a repository that happens to use that name.

Should and should not trigger

Trigger: “add a .gos module in this Gossamer repository,” “review this Gossamer project.toml or project.lock,” “fix this Gossamer gos check,” “make a Gossamer goroutine safe,” “build an existing Gossamer AOT binary,” “add a Gossamer Rust binding,” or “perform this explicitly requested bounded Gossamer target/feature proof.”

Do not trigger: “update the ChainSafe Gossamer Go node,” “write a Go channel,” “package a generic Docker image without Gossamer sources,” “choose a language/toolchain,” or “I need a standalone Wasm artifact; what language should I use?” A generic selection request belongs to the project’s comparison process; load this skill only after Gossamer is selected, except for an explicitly bounded Gossamer evaluation/proof. Automation-language selection belongs first to script-engineering.

What it is—and is not

The documented properties are language and toolchain facts. Choosing Gossamer is an adoption decision, not proof of performance, binary-size, startup-time, memory-use, or latency parity with any alternative. Do not invent universal benchmark claims; measure the target workload with a checked-in benchmark and its inputs.

WebAssembly Composition

Load webassembly-engineering when a Gossamer task needs a general WebAssembly decision: a WAT or .wasm artifact, WASI or WIT, the Component Model, host/guest contract, runtime or target selection, capability grants, or Wasm packaging and deployment. That skill owns those Wasm boundary and compatibility decisions. This skill retains Gossamer source, gos, project.toml/project.lock, compiler and binding mechanics, and its documented target constraints: Gossamer does not emit supported standalone Wasm artifacts, and its browser VM has its own stated restrictions. The Wasm skill does not establish Gossamer language, compiler, binding, browser VM, or supported-target claims.

Adoption decision

Use repository evidence, an explicit target tier, and a small proof program before committing a product to this pre-1.0 language.

Prefer a demonstrably better alternative class when a requirement conflicts:

Repository-first workflow

1. Read repository instructions and preserve unrelated changes. Before any routine gos command, inspect project.toml for [rust-bindings]. Every Rust binding is both a native-code trust boundary and a dependency/supply- chain boundary. Before accepting or executing any binding, unconditionally load security-review, security-review-evidence, and dependency-supply-chain-review. Keep all security evidence sanitized. Inspect project.toml, project.lock, workspace members, src/, tests/, nearby .gos modules, CI, deployment files, and existing gos commands before editing. Identify whether the project is a binary, library, workspace, binding host, or application.
2. Start gos to record its REPL startup banner (which includes the installed version), then run gos feature-status. The latter is authoritative for lifecycle state: Stable has the stated compatibility commitment; Shipped is available but unprotected; Experimental may change or disappear; Planned is not an implementation commitment. Standard-library modules default to Experimental until explicitly stabilized.
3. Identify the resolved entry and layout from project.toml and working local conventions. Current official sources conflict: SPEC.md §6.3 describes directory-based modules, root-level .gos contributions to the root module, subdirectory modules, and optional mod.gos; Writing Libraries describes each .gos file as a module, subdirectories requiring mod.gos, and root mod name; declarations. Do not infer inclusion or declarations from either description. When layout matters, make a minimal gos check probe with the installed toolchain, record its version and result/diagnostic, and follow the repository’s working convention for the active change. Report this document conflict as residual version risk.
4. Inspect [dependencies], [trusted-publishers], [rust-bindings], any custom registries, Cargo lock/configuration for bindings, and the lockfile before changing sources. Treat a changed publisher key, checksum, source URL, git revision, dependency, prebuilt input, or binding as a reviewable trust change. A trusted-publisher key from the checkout is not independent identity evidence; authenticate it through an approved independent channel.
5. Determine the execution and deployment tiers required: pure VM, JIT-enabled VM, host AOT, or cross-target AOT. Re-check the live supported-target matrix and local toolchain; acceptance of a triple or a successful local link is not support evidence.
6. State an observable behavior and the smallest module/API boundary that owns it. Add or update focused tests before broad refactoring. Keep public items, errors, concurrency ownership, and feature status explicit.
7. Make the smallest coherent change. Run a narrow check and test first, then the repository's documented formatting, lint, test, and target lanes.
8. Report exact gos version/feature-status and target evidence observed, manifest/lockfile impact, commands run, outcomes, skipped tiers, and remaining pre-1.0 or Experimental risk.

Module layout, imports, and visibility

Do not treat either current documentation model as universal. Inspect project.toml, neighboring source layout, and local conventions, then use a minimal gos check probe when a new file, directory, module declaration, or import path matters. Record the installed gos version and probe result/diagnostic; the installed toolchain plus the repository’s working convention is decisive for the active change, while the documentation conflict remains residual version risk.

The non-conflicting guidance is to use use, not import, to bind paths, and to use pub for an item intended to be visible outside its local scope. Do not add a Go-style source package declaration.

Toolchain: use only confirmed commands

Run commands against the repository-selected file or project path; do not assume a command, target, optional flag, formatter policy, or directory layout not evidenced locally. gos check establishes parsing, resolution, typing, and match exhaustiveness; it does not prove execution or compiled behavior.

Command effects and Rust-binding gate

With [rust-bindings], treat the following as consequential rather than routine read-only operations. A per-project Rust runner can build or execute binding code; Cargo build scripts, procedural macros, native archives, and the binding itself can inherit host environment access and privileges. Typed ABI validation is not sandboxing.

Host permission prompts classify requested actions; they do not sandbox transitive tool, Cargo, native-code, filesystem, network, environment, or credential effects. For an untrusted/external repository, execution requires explicit authority and an isolated, credential-free outer environment; stop if that environment is unavailable.

The separate editor-support repository contains integrations for VS Code, Vim, Neovim, Helix, Emacs, Sublime, and Zed. Its documented surface may lag the compiler; inspect its version and per-editor installation method before installing or treating features as available.

Installation and release evidence

Official documentation prose may say “build from source today” and promise prebuilt binaries later, while current GitHub Releases can contain downloadable assets. Treat that as a live-documentation conflict. Before prescribing an installer or download URL, verify the current installation documentation, latest release API, asset provenance/checksums, target, and local gos behavior. Do not hard-code a release version as current.

Language essentials

Bindings, values, and managed references

• Bindings are immutable by default; write let mut value only when the binding must be reassigned or mutated. This makes mutation reviewable in the declaration and is checkable by the type checker.
• T can be a copied primitive/value or a managed shared aggregate. Assignment of managed String, Vec<T>, structs, enums, and closures does not transfer ownership; it shares backing storage. Use .clone() when the contract requires a deep copy.
• &T is a non-null managed shared alias and &mut T is a managed alias granting write-through access. Neither has Rust lifetimes, moves ownership, or proves global alias exclusivity. &mut is not a concurrency guarantee. Synchronize cross-goroutine shared mutation with channels, std::sync, or atomics; do not reason from &mut alone.
• A function requiring &mut T must receive an explicit &mut place; a bare value is not implicitly made mutable. The checker catches common direct sibling aliases, but complex aliases remain the programmer's responsibility. References cannot cross a go/channel boundary—share owned managed values deliberately and synchronize them.

Enums, errors, matching, and pipelines

Option<T> is Some(T) or None; Result<T, E> is Ok(T) or Err(E). Use them at fallible or absent-value boundaries rather than nulls or exceptions. Use exhaustive match for state alternatives and keep each arm’s behavior testable.

use std::errors

fn maybe_even(n: i64) -> Option<i64> {
    if n % 2 == 0 { Some(n) } else { None }
}

fn require_even(n: i64) -> Result<i64, errors::Error> {
    match maybe_even(n) {
        Some(value) => Ok(value),
        None => Err(errors::new("expected an even integer")),
    }
}

fn add_one_to_even(n: i64) -> Result<i64, errors::Error> {
    let value = require_even(n)?
    Ok(value + 1)
}

std::errors is currently Experimental; verify its status with gos feature-status before relying on it. This source-supported example is intentionally unexecuted here: do not claim it passed without a disposable, isolated no-manifest/no-dependency/no-binding probe and its recorded installed gos version and result.

? propagates Err from Result (converting the error when an appropriate conversion exists) or None from Option; the enclosing function must return the corresponding compatible Result or Option. Do not unwrap without a testable invariant and a useful failure policy.

|> is the forward pipe. Its right side must be callable; standard-library free functions intended for piping conventionally take the data argument last. Use a pipe for a clear transformation sequence, not to conceal effects, resource lifetimes, or error handling. ? binds more tightly than |>.

Entry files and top-level statements

The resolved entry file may contain bare top-level statements, which become an implicit main. If a top-level statement uses ?, that implicit main returns Result<(), errors::Error>. Use exactly one entry form: top-level statements or explicit fn main, never both. Modules and library files contain items only. Top-level let bindings are locals of that implicit main; use const or static for deliberate cross-function state.

Goroutines and channels

go expression starts a goroutine; spawn returns a JoinHandle<T> whose join() reports either a normal value or a captured panic. channel<T>() creates typed sender/receiver endpoints, and select chooses among ready operations. Give every producer/consumer a termination, cancellation, and ownership story; test backpressure, closed-channel/error paths, and shutdown.

Do not use fire-and-forget go when a result, panic, cleanup, or lifecycle must be observed—use spawn and join or a channel protocol. Do not share mutable structures because aliases compile; prove synchronization with a gos test --race test and a deterministic shutdown test.

For a local CPU-bound Gossamer workload whose main design problem is data or task decomposition, partition sizing, bounded execution, deterministic reduction, cancellation, or nested-parallelism control, compose with parallelism-engineering. It owns that cross-language parallel design; this skill owns Gossamer goroutine, channel, spawn, memory-model, and gos test --race mechanics.

Do not route ordinary goroutine lifecycles, channels, select, async I/O, or concurrency safety to parallelism-engineering; they remain Gossamer mechanics. Spark/PySpark execution remains with data-platform-engineering, not local parallelism engineering.

Memory, cycles, Weak, and arenas

Compiled tiers use RC and collect only eligible thread-local reference cycles; their collection is not a tracing-GC promise. The bytecode VM used by gos run does not collect reference cycles. Values shared across goroutines are not eligible for that compiled-tier cycle collector. Use Weak<T> to break a cycle whenever cross-goroutine reclamation or cross-tier identical liveness matters; upgrade() returns Option<T>.

Use arena { ... } for a short-lived object graph that is constructed, processed, and discarded as one unit. It bulk-frees arena allocations on block exit, including early return, ?, and break. The compiler rejects detected escapes from an arena; structure the code so the block returns only a durable summary outside the arena. Never rely on an arena object, including a Weak reference to one, surviving its block.

runtime::arena_push() and runtime::arena_pop() are lower-level primitives that bypass the safer structured block’s balanced-lifetime guarantee. Do not use them without a bounded low-level review of every control-flow exit, allocation lifetime, and cleanup path.

Compile-time facilities and macros

comptime evaluates compile-time-known Gossamer expressions on the bytecode VM and folds a scalar or String result. typeInfo::<T>() provides compile-time reflection over named-struct fields; a for over it can be unrolled. codegen!(...) splices the String produced by a comptime fn as source and type-checks it at the call site. Use these only when generated code is clearer, smaller in source, and covered by ordinary caller-facing tests.

Gossamer has a fixed documented macro set (including formatting/output and build-time validation macros such as regex! and sql!). It does not support arbitrary user-defined declarative/procedural macros, macro grammar, hygiene, or token-tree DSLs. Prefer a function, generic, trait, or comptime helper; do not propose Rust macro_rules! or procedural-macro architecture.

Numeric behavior

i128 and u128 are rejected at type-check time on every tier. Every numeric conversion requires an explicit as cast. For integer types up to 64 bits, arithmetic runs with documented 64-bit runtime semantics, not the declared narrow type’s wrap width: 200u8 + 200u8 is 400. To request narrow wrapping, cast explicitly after the operation; use checked_*, wrapping_*, saturating_*, or overflowing_* methods when their stated behavior is the contract. Test boundaries, signs, shifts, and conversions; do not import Rust/Go debug-overflow expectations.

Rust bindings, not general FFI

Gossamer source has no raw-pointer types, source-level extern "C", or general C/C++ FFI. Its supported native integration surface is a typed Rust binding: declare a crate under [rust-bindings] in project.toml; the Rust crate uses gossamer-binding and register_module!; import the exposed module with use in .gos. The ABI supports typed values such as integers, floats, strings, tuples, vectors, Option, Result, opaque handles, byte buffers, and callbacks.

Every Rust binding is native code and a supply-chain boundary, even when its ABI types validate. Its Cargo crate/git/path/prebuilt resolution is outside project.lock; Cargo may not use --locked or --offline and can independently resolve/build inputs. Before accepting or executing any binding, apply the unconditional three-skill gate above, require explicit execution authority, and require evidence appropriate to the input: Cargo lock/checksums/full immutable revision for Cargo sources, or signed-prebuilt provenance and digest for prebuilt inputs. Write a boundary test for type conversion, error conversion, panic behavior, and every required execution/deployment tier only after that gate.

Practices that produce evidence

Anti-patterns and replacements

Testing, trust, deployment, and completion

Tests and debugging

Test pure functions, enum transitions, Option/Result errors, module public APIs, numeric boundaries, binding conversions, and deterministic concurrency units. Add integration tests for filesystem/network/process/database adapters only where the actual application contract needs them; isolate external state and avoid live credentials. Test a compiled executable for deployment behavior that a VM run cannot establish. Use test-driven-development when executable examples should drive a behavior change, and systematic-debugging for an active, unexplained compiler, runtime, race, or deployment failure.

Security and package trust

Do not treat automatic memory management, a race detector, registry signatures, or a lockfile as a complete security claim. Validate untrusted input, paths, serialization, command/process boundaries, auth, secrets, and deployment privileges at the application boundary. Load security-review for implemented security controls or trust-boundary changes. Whenever security evidence is handled, load security-review-evidence and keep all such evidence sanitized.

Before any registry, publisher-key, dependency, lockfile, vendoring, publication, or provenance work—including adding or updating registry, git, path, or Rust-binding dependencies; changing project.toml, project.lock, vendored sources, package publication, or release tooling—load dependency-supply-chain-review. Use the following source-specific evidence; no lockfile or vendoring shortcut expands another source type’s guarantee.

gos publish --dry-run suppresses upload only. It can read and package the source tree, may access and use a publisher key for signing, and can leave a temporary archive depending on interruption and temporary-directory settings; it can also succeed with no configured signature. Before any dry-run or publication attempt, require explicit publication and key-use authorization, an approved package-content allowlist, a secret scan, a private restrictive- permission temporary location, and cleanup verification. Observe a valid signature; missing signing is a hard stop for publication. Dry-run is neither publication approval nor proof that no secret would be uploaded.

Targets and deployment

At the time these docs were checked, Tier 1 listed x86_64-unknown-linux-gnu, aarch64-unknown-linux-gnu, aarch64-apple-darwin, and x86_64-pc-windows-msvc; Tier 2 listed the Linux-musl AOT targets x86_64-unknown-linux-musl and aarch64-unknown-linux-musl. Intel macOS is artifact-only, and several Wasm/RISC-V triples may be registered but are unsupported. This matrix changes: re-check the live docs, the release matrix, and the local toolchain for every deployment rather than treating this list as evergreen.

Native output is an ELF/Mach-O/PE binary linked with the Gossamer runtime; the runtime/deployment details and static-versus-dynamic requirements still depend on target and build setup. Build and smoke-test the exact release artifact in the target environment. For checked-in CI/release automation, publication, or artifact provenance, load ci-release-engineering. For Docker/OCI or Compose implementation, load container-engineering; do not copy an example image recipe without confirming base-image, libc/musl, target, user, port, secret, and health requirements.

In the current browser VM/playground, absent additional host bridges, browser execution means the bytecode VM itself runs in a Wasm sandbox. It cannot access filesystem, sockets, processes, SQL, or the listed native facilities, and its single-threaded goroutines run cooperatively to completion rather than interleaving like native targets. It is suitable only for behavior compatible with those constraints.

Related-skill routing

• Load api-design when a public service, SDK, CLI, serialized, event, or error contract is being designed or changed—not merely because Gossamer implements it.
• Load observability-engineering for durable logs, metrics, traces, correlation, alerts, or SLOs; add the security skills when those signals can expose sensitive data.
• Load documentation-engineering when reader-facing docs, // documentation tested by gos test, examples, migration notes, or generated API docs are in scope.
• Load random-data-identifiers when IDs, tokens, randomness, fixtures, collision behavior, or deterministic seeds are a design concern. Keys, nonces, salts, IVs, tokens, and every other security-sensitive random value also require security-review and security-review-evidence.

Completion evidence

Before handoff, provide:

1. changed .gos, manifest, lockfile, binding, test, and deployment files;
2. observed toolchain/feature-status and target-support evidence;
3. exact commands and pass/fail/skipped results for format, check, lint, test, race, benchmark (if claimed), and relevant VM/AOT lanes;
4. tests proving changed behavior, error paths, concurrency lifecycle, numeric boundaries, or FFI conversions as applicable;
5. dependency/publisher/provenance review status, Rust-binding execution authority/outer-isolation evidence where applicable, and sanitized security evidence where required; and
6. residual Experimental/pre-1.0, target, browser, ecosystem, or deployment risk. Never convert missing evidence into a compatibility, security, or performance guarantee.

References: official Gossamer sources and conceptual context

Official Gossamer sources

• Gossamer documentation home: language overview, orientation, and current installation prose; verify it against releases before prescribing installation.
• Language specification: normative Stable semantics, lifecycle definitions, syntax, managed references, numeric behavior, concurrency, packages, bindings, and target contract.
• Toolchain reference: gos subcommands, formatting/lint/testing/benchmarking, package commands, REPL, LSP, and MCP details.
• Running guide: command cheat-sheet, pure-VM --no-jit, entry handling, and development-watch limitations.
• Skill card: concise agent-facing language/toolchain orientation and project layout.
• Memory model: RC, Weak<T>, cross-tier cycle behavior, alias semantics, and arenas.
• Supported targets: evidence-tiered target matrix and unsupported-target caveats; re-check per release.
• WebAssembly: browser VM sandbox, cooperative browser goroutines, and no standalone Gossamer-to-Wasm output.
• Writing libraries: manifest, lockfile, modules, registries, publisher trust, and publishing workflow.
• Security: upstream security posture and stated gaps; it is not a substitute for application security review.
• Lints: current lint IDs and explanations; use the installed toolchain to confirm availability.
• Comptime: compile-time evaluation, typeInfo, reflection-driven code, and codegen! limits.
• [Top-level statements](https://gossamer-lang.org/docs/langua

…(truncated)