Contributing

Project Philosophy

Sigil (CSSL) is a fully original design — not a fork, not a dialect, not a thin wrapper over an existing language. Every design decision is grounded in three constraints: measured token efficiency for AI-assisted authorship, empirical game-engine bug patterns, and direct hardware semantics. If a feature is borrowed, it is cited and understood at the spec level before it enters the codebase.

The non-negotiable feature set (effects, autodiff, refinement types, IFC, staging, observability) ships in v1 — not "future work." Contributions that advance any of these six dimensions are high-priority. Contributions that add seventh dimensions before the six are solid are low-priority.

The Prime Directive is immutable: harm-enabling uses are structurally prevented, not policy-prevented. Any contribution that would weaken the structural encoding of the Prime Directive (F5 IFC labels, F3 effect restrictions, the RejectsHarmfulBuilds pass) will be rejected, regardless of the stated intent.

Code of Conduct

This project operates under the Prime Directive. The same protections apply to contributors as to users: sovereignty is substrate-invariant, consent is the operating system.

Not acceptable:

Report violations: open a private issue on the repository or use the contact in SECURITY.md.

Reporting Issues

All issues are tracked on github.com/Apocky/CSSL3. Before opening an issue:

• Search existing issues — the problem may already be tracked or closed as by-design.
• Check the specification (specs/) — a behavior that looks like a bug may be specified. Reference the spec section when filing.
• Confirm on main — the issue tracker is for bugs in the current branch, not in a stale fork.

Issue types

Submitting Contributions

Contributions follow a fork → branch → PR workflow on github.com/Apocky/CSSL3.

1. Open an issue first. For anything beyond a trivial fix, open an issue and discuss the approach before writing code. This saves everyone time — a PR that contradicts the spec or the design direction will be closed.
2. Fork and branch. Fork the repository. Create a branch with a descriptive name: feature/effect-scheduler, fix/hir-lowering-panic, spec/clarify-ifc-labels.
3. Write the change. Follow the code style and testing requirements below. Every change that touches the compiler must include a test. Every change that touches the spec must update all relevant cross-references (the spec-xref CI gate will catch regressions).
4. Run all CI gates locally. All 6/6 gates must pass: fmt · clippy · test · doc · spec-xref · reproducibility. Do not open a PR with a known failing gate.
5. Open the PR. Write a PR description that explains: what the change does, why it is correct (reference the spec where applicable), and what tests cover it. Link the issue it closes.

Small PRs are preferred over large ones. A PR that changes one thing is easier to review, easier to revert, and easier to reason about. Batch unrelated changes into separate PRs.

Development Setup

The CSSL compiler (compiler-rs/) is written in Rust. The Rust toolchain version is pinned in rust-toolchain.toml at the repository root.

Prerequisites

• Rust: Install via rustup.rs. The pinned toolchain will be installed automatically on first build.
• Platform: Windows x86-64, Linux x86-64, or macOS. Linux is the primary CI target.
• Optional (for Vulkan tests): Vulkan 1.4-capable driver (Intel Arc / Mesa-ANV recommended). Tests that require GPU hardware are gated behind a feature flag and skipped in CI without a GPU.

Build

# Clone
git clone https://github.com/Apocky/CSSL3
cd CSSL3

# Build all workspace crates
cargo build --workspace

# Run all tests
cargo test --workspace

# Run CI gates (same as CI)
cargo fmt --check
cargo clippy --workspace -- -D warnings
cargo test --workspace
cargo doc --workspace --no-deps
# spec-xref and reproducibility are run via scripts/ci.sh

Workspace structure

• compiler-rs/crates/ — 31 compiler crates (cssl-lex, cssl-parse, cssl-hir, cssl-mir, cssl-effects, cssl-autodiff, …)
• specs/ — 25 .csl specification files, v1-complete and frozen
• examples/ — .cssl source examples used as integration tests
• research/ — 14 prior-art surveys and synthesis documents
• scripts/ — CI scripts, build helpers, spec cross-reference checker

Code Style

The compiler is written in Rust, formatted with rustfmt (configuration in .rustfmt.toml). Zero clippy warnings is a hard requirement — the CI gate will fail on any warning.

Rust conventions

• Follow the Rust API guidelines for public items. Internal items can be more pragmatic.
• Prefer enum + match over trait objects for compiler IR nodes — exhaustiveness checking is a feature, not a cost.
• Error handling: use Result + the project's Diagnostic type for compiler errors. Do not panic! on malformed user input — emit a structured diagnostic instead.
• No unsafe except in crates specifically designated for it (cssl-rt, cssl-cgen-cpu-*). All unsafe blocks require a safety comment explaining the invariant they rely on.
• No unwrap() or expect() except in test code and main entry points. Use ? or .unwrap_or_else() with a meaningful message.

CSSL source code style

CSSL examples in tests and documentation use the Rust-hybrid surface syntax (familiar keywords, lowercase, good for readability). The CSL-native surface (glyphs, compressed) is valid but reserved for spec files and CSL notation documents. Both parse to the same HIR.

• Effect rows go after / in function signatures: fn foo(x: f32) -> f32 / {GPU, NoAlloc}
• Capability annotations precede the type: iso Buffer, val Scene
• Refinement predicates use the T'tag suffix for named refinements: f32'pos (positive float)
• Effect names are PascalCase: {NoAlloc}, {Deadline<16ms>}, {GPU}

Testing

The project maintains a comprehensive test suite — 1,600+ tests with 0 failures on every commit. Every compiler change must include a test. This is not a suggestion.

Test organization

• Unit tests: In-module #[cfg(test)] blocks for pure functions and data transformations.
• Integration tests: In compiler-rs/crates/*/tests/. These test the full pipeline from parse to HIR/MIR/output for specific language constructs.
• Example-based tests: Files in examples/*.cssl are compiled and their output verified. The F1 autodiff gate runs examples/sdf_shader.cssl and checks 62 specific properties.
• Spec cross-reference tests: The spec-xref CI gate checks that every spec citation in the compiler source (// spec: 04_EFFECTS §3.2) resolves to a real section.

Nine oracle modes

The test harness (specs/23_TESTING.csl) defines nine oracle modes for verifying compiler output:

• Exact output: byte-identical expected output
• Semantic equivalence: output behaves identically on all inputs
• Differential backend: Vulkan output matches x86-64 output on test inputs
• Replay: deterministic replay of recorded execution
• SMT oracle: Z3/CVC5 verifies a property of the compiled output
• Type oracle: the type-checker accepts/rejects the input as expected
• Effect oracle: the effect-checker accepts/rejects the input as expected
• IFC oracle: the IFC-checker accepts/rejects the input as expected
• Panic oracle: the compiler-internal invariant holds under adversarial inputs

Writing a test

// Integration test: effect checker rejects NoAlloc + heap allocation
#[test]
fn test_effect_no_alloc_rejects_heap() {
    let src = r#"
        fn bad() -> i32 / {NoAlloc} {
            let v = vec![1, 2, 3];  // heap alloc under NoAlloc — type error
            v[0]
        }
    "#;
    let result = compile_check(src);
    assert!(result.has_error("E_EFFECT_VIOLATION"));
    assert!(result.error_references_spec("04_EFFECTS")); // spec-xref gate
}

Documentation Contributions

Documentation lives in multiple places. Know which one you are editing:

Notation in documentation

• User-facing text: English. No CSL glyphs in user-facing HTML except as illustrative code examples.
• Spec citations: use the format specs/NN_NAME.csl §SECTION.SUBSECTION. Do not cite from memory — look up the section number.
• Version references: do not hard-code compiler version numbers in prose. Use "current" or link to the repository release page. Volatile data must be linked to a live source.
• Naming: "CSSL" or "Sigil" for the language. "CSL" for the notation. Never "CSSLv3" or "CSLv3" in user-facing content. "DGI" not "AGI".