# cssl.dev — Sigil/CSSL Language + CSL Notation: Full Reference

LLM-indexable reference for cssl.dev. Two distinct things:
- **Sigil / CSSL** — the programming language (compiler live, WIP)
- **CSL** — the specification notation (stable, v1.7.0)

Licensed CC BY 4.0 — attribute "Sigil / CSL reference — Shawn Wolfgang Michael Baker,
licensed CC BY 4.0 (https://cssl.dev)".

This document is the LLM-indexable reference derived from cssl.dev. Content is
canonical at the HTML pages; this file may lag by one deploy cycle.

Links:
- Sigil home: https://cssl.dev/
- CSL reference: https://cssl.dev/CSLv3
- Documentation: https://docs.cssl.dev
- Sigil repository: https://github.com/Apocky/CSSL3
- CSL repository: https://github.com/Apocky/CSLv3

---

# Part 1 — Sigil / CSSL: AI-First Game Engine Language

## §A · What is Sigil / CSSL

Sigil and CSSL (Caveman Sigil Substrate Language) are two names for the same
programming language. It is a hardware-grounded language that compiles a single
source file to both native x86-64 (AVX2+FMA3) and SPIR-V (Vulkan compute
shaders). It is designed from the ground up for AI-assisted development, with
syntax optimized for token efficiency, type safety, and direct hardware mapping.

Stage-0 compiler is live in Rust (1,600+ tests passing). Stage-1 bootstraps in
Sigil itself. This is a forward-design language, not yet a shipped production
toolchain.

Core thesis: **density = sovereignty.** Every syntax decision is justified by
measured token efficiency, empirical AI code-generation error patterns, and
direct hardware semantics.

## §B · Language Syntax Overview

File extension: `.cssl`

Functions:

    fn dot(a : vec3, b : vec3) -> f32 / {Pure} {
      a.x * b.x + a.y * b.y + a.z * b.z
    }

- `fn NAME(PARAMS) -> RETURN / {EFFECTS} { BODY }`
- Effect row after `/` — zero or more effect labels in `{}`
- Type annotations use `:` (bind/has)
- `->` for return type and control flow
- Blocks use `{ }`, expressions are the body

Primitives: `i8 i16 i32 i64 u8 u16 u32 u64 f32 f64 bool str bytes`
Vector types: `vec2 vec3 vec4 mat2 mat3 mat4 quat`

Let bindings:

    let dist : f32<m>  = 10.0
    let time : f32<s>  = 2.0
    let speed = dist / time  // f32<m/s> — inferred

Dimensional units:

    unit m    unit s    unit rad    unit px

Unit errors are compile errors. `f32<m> + f32<s>` does not compile.

Coordinate spaces:

    space world    space view    space clip

Mixing coordinate spaces is a type error. `vec3<m, world> + vec3<m, view>` does
not compile. The compiler knows which space every vector lives in.

Structs and enums:

    struct Vertex { pos : vec3<m, world>, uv : vec2 }
    enum Method = GET | POST | PUT | DELETE

Annotations (attributes):

    @differentiable    // enables AD (forward + backward)
    @fragment          // GPU fragment shader entry point
    @vertex            // GPU vertex shader entry point
    @compute           // GPU compute shader entry point

## §C · Effect System

Effect rows appear after `/` in function signatures:

    fn render(scene : Scene) -> Frame / {GPU, Deadline<16ms>, NoAlloc} { ... }

Effect labels are verified at type-check time, not runtime. Calling a
`/ {NoAlloc}` function that allocates is a compile error.

Built-in effects:
- `GPU` — function runs on GPU; may not use CPU-only primitives
- `CPU` — function runs on CPU (default)
- `Pure` — no side effects, no IO, deterministic
- `NoAlloc` — no heap allocation permitted
- `Deadline<N>` — must complete within N ms; verified via worst-case analysis
- `Tainted<label>` — IFC label; data provenance tracking through call graph
- `Sync` / `Async` — execution model

Effect rows compose:

    fn fast_pure(x : f32) -> f32 / {Pure, NoAlloc, CPU} { x * x }

A function calling `fast_pure` from a GPU context is a type error.

## §D · Automatic Differentiation

Mark any eligible function `@differentiable`:

    @differentiable
    fn sphere_sdf(p : vec3, r : f32) -> f32 {
      length(p) - r
    }

The compiler generates both forward and backward pass variants. Call sites use:

    fwd_diff(sphere_sdf)(p, r)    // forward mode: (value, gradient)
    bwd_diff(sphere_sdf)(p, r)    // reverse mode: cotangent propagation

AD legality is checked at compile time — non-differentiable ops (conditionals on
floats, integer casts) in `@differentiable` functions are compiler errors.

Surface normals computed analytically (no finite differences):

    fn surface_normal(p : vec3) -> vec3 {
      normalize(bwd_diff(scene_sdf)(p).d_p)
    }

The `@differentiable` annotation enables AI agents to write gradient code
without AD expertise. The compiler handles the math.

## §E · SMT Verification

Type-level invariants are discharged at compile time by Z3 and CVC5:

    fn safe_index(arr : [f32; N], i : u32) -> f32
      requires i < N
    {
      arr[i]
    }

The `requires` clause is a precondition. Callers must prove `i < N` at
the call site — either via static analysis or by providing a proof term.
Unprovable obligations are compile errors, not runtime panics.

Refinement types:

    type PosFloat = { x : f32 | x > 0.0 }
    type BoundedIndex<N> = { i : u32 | i < N }

The compiler reduces refinement constraints to SMT queries and dispatches to Z3
(preferred) or CVC5 (fallback). Proof failures surface as structured diagnostics
with the failing constraint and context.

## §F · GPU Effects and SPIR-V Emission

Sigil emits SPIR-V 1.3+ for Vulkan compute and graphics. The same source file
compiles to both CPU (x86-64 via Cranelift at stage-0) and GPU.

Entry points are annotated:

    @vertex
    fn vert_main(in : VertexInput) -> VertexOutput / {GPU} { ... }

    @fragment
    fn frag_main(in : FragInput) -> vec4 / {GPU, Deadline<16ms>} { ... }

    @compute workgroup_size(64, 1, 1)
    fn compute_main(id : ComputeId) / {GPU, NoAlloc} { ... }

GPU-only restrictions enforced at type-check:
- No heap allocation in `/ {GPU}` functions
- No recursion (SPIR-V requirement)
- No function pointers
- Texture sampling only in `@fragment` entry points

SDF as compiler-aware primitive:

    type SDF = fn(vec3) -> f32  // Lipschitz ≤ 1 tracked by compiler

SDF algebra (union, intersection, smooth blend) preserves the Lipschitz
invariant. The compiler tracks it; you cannot accidentally break SDF properties.

## §G · API Surface Summary

**Compiler CLI (`csslc`):**

    csslc run hello.cssl              # compile + run (dev mode, Cranelift)
    csslc build hello.cssl            # compile to binary (release mode, Cranelift)
    csslc check hello.cssl            # type-check + SMT only; no codegen
    csslc emit-spv hello.cssl         # emit SPIR-V only
    csslc emit-x64 hello.cssl         # emit x86-64 assembly
    csslc test                        # run test suite

**Language builtins:**

    // Math
    length(v)  normalize(v)  dot(a, b)  cross(a, b)  mix(a, b, t)
    sin(x)  cos(x)  sqrt(x)  abs(x)  clamp(x, lo, hi)  min(a, b)  max(a, b)
    floor(x)  ceil(x)  fract(x)  pow(x, e)  log(x)  exp(x)

    // SDF primitives
    sphere_sdf(p, r)   box_sdf(p, half)   plane_sdf(p, n, d)
    sdf_union(a, b)    sdf_intersect(a, b)  sdf_smooth_union(a, b, k)

    // AD
    fwd_diff(f)(args)  bwd_diff(f)(args)

    // Type conversions
    as_f32(x)  as_i32(x)  as_u32(x)  bits(x)

**Standard library modules (docs.cssl.dev):**

    cssl::math        // extended math, easing, noise
    cssl::color       // color spaces (linear, sRGB, HSL, Oklab)
    cssl::geom        // geometry, BVH, mesh
    cssl::physics     // rigid body, constraints, collision
    cssl::audio       // DSP, convolution, synthesis
    cssl::net         // async networking

## §H · Stage-0 Compiler Pipeline

    Source (.cssl)
      → Lexer (hand-written, zero-alloc)
      → Parser (LL(2), produces CST)
      → HIR lowering (name resolution, import graph)
      → AD legality check (@differentiable gates)
      → MIR lowering (SSA + structured regions)
      → AD walker (emits fwd/bwd MIR variants)
      → SMT translation (Z3/CVC5 dispatch)
      → Codegen: Cranelift (stage-0) | bespoke x86-64 emitter (stage-1+) | SPIR-V emitter

All stages are unit-tested independently. The 1,600+ test suite covers:
- Parser correctness (round-trip)
- HIR well-formedness
- AD legality acceptance/rejection
- MIR invariants
- SMT correctness (known-satisfiable + known-unsat)
- SPIR-V validity (spirv-val)
- End-to-end cross-compilation

---

# Part 2 — CSL: Caveman Spec Language

Full reference content derived from cssl.dev/CSLv3. Licensed CC BY 4.0 —
attribute "Sigil / CSL reference — Shawn Wolfgang Michael Baker,
licensed CC BY 4.0 (https://cssl.dev)".

Upstream source repository: https://github.com/Apocky/CSLv3
Specifications: specs/00_MANIFEST.csl through specs/15_M2_METRIC.csl

---

## §1 · What is CSL

CSL (Caveman Spec Language) is a formal, versioned notation system for
ultra-dense specification. It achieves 5-6× compression over English prose
while preserving implementation fidelity. Every design decision is justified
by measured token efficiency under Claude and GPT-4 BPE tokenizers,
information-theoretic entropy, and empirical AI code-generation error patterns.

**CSL is a notation system, distinct from the CSSL/Sigil compiler language.**
CSSL (Caveman Sigil Substrate Language) and Sigil are two names for the same
language. CSL is separate: it is the notation used to write specs, reason in
chain-of-thought, and drive the CSL reference compiler. They share the "Caveman"
density thesis but compile through different pipelines.

## §2 · Core Axiom

**density = sovereignty**

The symbols a system uses to think should match how that system actually
thinks. For AI, that means fewer tokens carrying more meaning. Every
byte is a cognitive tax paid by every reader — human or model. Dense
notation restores the reader's agency over their attention.

## §3 · Triple Scope

CSL operates at three scopes simultaneously:

1. **Human↔AI spec communication.** Apocky writes specs in CSL; AI
   collaborators read and extend them. Both sides share a notation
   optimized for the other's bottleneck.
2. **Agent chain-of-thought reasoning substrate.** CSL replaces
   English in internal reasoning blocks (`§P problem`, `§D decompose`,
   `§T trace`, `§S synthesis`, `§C check`). Shorter reasoning = more
   reasoning-per-token-budget.
3. **CSL reference compiler input.** LL(2) parseable, self-specifying.
   The compiler targets x86-64 and SPIR-V via IR (SSA + structured
   regions).

## §4 · Intellectual Ancestry

| Source        | Contribution |
|---------------|--------------|
| APL / J / k   | Symbol-first notation; dense operators as first-class primitives |
| Ithkuil       | Morpheme stacking; determinative suffixes; positional meaning |
| Sanskrit      | Compound classification (tatpurusha, dvandva, karmadhāraya, bahuvrihi, avyayibhava) |
| Peirce        | Existential graphs; reasoning visualization |
| Lojban        | Unambiguous parsing; predicate-argument structure |
| Math notation | Quantifiers, set operators, proof markers (∀ ∃ ∈ ∴ ∵ ∎) |
| TLA+ / B      | Modal operators for specification (MUST, SHOULD, MAY) |

## §5 · The Glyph System

Glyphs are organized into three tiers by frequency and learning
priority. **Tier 0** is the core 50-glyph set every contributor learns
first; **Tier 1** holds domain determinatives, type suffixes, and
APL-derived operators; **Tier 2** is domain-specific extensions.

Every Unicode glyph has a mandatory ASCII alias. Modern BPE tokenizers
can split a single Unicode symbol into 3-5 tokens, which destroys the
compression advantage. When a glyph costs 3+ BPE tokens, the ASCII form
is preferred.

### Tier 0 glyph inventory (selection)

| Glyph | ASCII | BPE | Meaning |
|-------|-------|-----|---------|
| §     | S:    | 1   | section / module / domain boundary |
| →     | ->    | 2-3 | then / yields / maps-to / flow |
| ←     | <-    | 2-3 | from / sourced / derives |
| ↔     | <->   | 2-3 | bidirectional / isomorphic |
| ⇒     | =>    | 2-3 | implies (logical) |
| ⊢     | \|-   | 2   | entails / proves |
| ∴     | .:.   | 2   | therefore |
| ∵     | :..   | 2   | because |
| ∎     | QED   | 2-3 | block-end / proof-end |
| W!    | W!    | 2   | MUST (hard requirement, inviolable) |
| R!    | R!    | 2   | SHOULD (strong recommend) |
| M?    | M?    | 2   | MAY (optional) |
| N!    | N!    | 2   | MUST NOT (prohibition) |
| I>    | I>    | 2   | INSIGHT / key claim |
| Q?    | Q?    | 2   | QUESTION / open |
| P>    | P>    | 2   | PUSH FURTHER |
| D>    | D>    | 2   | DECISION NEEDED |
| ✓     | [x]   | 1   | confirmed / true |
| ◐     | [~]   | 1-2 | partial / probable |
| ○     | [ ]   | 1   | pending / possible |
| ✗     | [!]   | 1-2 | failed / rejected |
| ⊘     | [?]   | 2-3 | no evidence / TBD |
| △     | [^]   | 2   | hypothetical |
| ▽     | [v]   | 2   | deprecated |
| ‼     | [!!]  | 2   | proven / immutable |
| .     | .     | 0-1 | tatpurusha compound (Y of X) |
| +     | +     | 1   | dvandva compound (X and Y) |
| -     | -     | 1   | karmadhāraya compound (Y that is X) |
| ⊗     | x*    | 2   | bahuvrihi compound (having X-Y) |
| @     | @     | 1   | avyayibhava (at / per / in scope of) |
| :     | :     | 1   | bind / has / definition |
| ::    | ::    | 1   | type-of / inherits |
| =     | =     | 1   | equals / assign |
| ≠     | !=    | 2   | not-equal |
| ∀     | all   | 2   | for all / universal quantifier |
| ∃     | any   | 2   | exists / existential quantifier |
| ∈     | in    | 2   | member-of |
| ∪     | \|+   | 2   | union |
| ∩     | &+    | 2   | intersect |
| ¬     | ~     | 2   | not / negation |
| ∧     | &&    | 2   | logical and |
| ∨     | \|\|  | 2   | logical or |
| ⊕     | xor   | 2   | exclusive or |
| ≡     | ===   | 2   | structurally identical |
| ≈     | ~=    | 2   | approximately equal |
| ≥     | >=    | 2   | greater-or-equal |
| ≤     | <=    | 2   | less-or-equal |
| ∞     | inf   | 2   | unbounded |
| ∅     | nil   | 2   | empty set / nothing |
| ⟨ ⟩   | <\| \|> | 2 ea | tuple / record / entity-property |
| ⟦ ⟧   | [[ ]] | 2 ea | formula / equation / meaning-of |
| ⌈ ⌉   | [^ ^] | 2 ea | constraint / upper-bound / invariant |
| ⌊ ⌋   | [_ _] | 2 ea | floor / lower-bound / precondition |
| «  »  | <<Q Q>> | 2-3 | quotation / external API |
| ⟪ ⟫   | <<T T>> | 3 ea | temporal / phase |

Tier 1 adds domain determinatives (§ ∫ ⊞), type suffixes ('d 'f 's 't
'e 'm 'p 'g 'r), temporal operators, pipeline/dataflow glyphs, and
APL-derived operators (reduce, scan, each, compose). Tier 2 holds
physics and material-science glyphs (ρ μ σ κ ∇).

Full tier inventory: specs/01_GLYPHS.csl.
Full ASCII alias table: specs/12_TOKENIZER.csl.

## §6 · Five Compound Types

Rather than using English prepositions and articles, relationships
between terms are encoded by the operator joining them. From Sanskrit
samāsa classification:

- **tatpurusha** `.` — "Y of X". `player.hp` = "hp of player". One
  dimension of ownership / membership / description.
- **dvandva** `+` — "X and Y". `cpu+gpu` = "both CPU and GPU".
  Unordered conjunction.
- **karmadhāraya** `-` — "Y that is X". `static-mesh` = "mesh that is
  static". Adjectival qualification.
- **bahuvrihi** `⊗` — "having X-Y". `fire⊗resist` = "having fire
  resistance". Possessive metaphor.
- **avyayibhava** `@` — "at / per / in scope of". `@frame` = "per
  frame, at frame scope".

## §7 · Slot Grammar

Position carries meaning. Every statement fits a template:

    [EVIDENCE?] [MODAL?] [DET?] SUBJECT [RELATION] OBJECT [GATE?] [SCOPE?]

Defaults are **silent** — only write non-default values:

- Default evidence: `✓` (confirmed)
- Default relation: `:` (bind)
- Default scope: global

Example expansion:

    Terse:   hp : f32
    Full:    ✓ W! 'p hp : f32 @ player

The terse form is the canonical writing; the expansion is what the
parser resolves it into. Silent defaults shrink the surface area without
losing information.

## §8 · Morpheme Stacking

Base lemmas take suffixes stacked in a fixed order:

    BASE.aspect.modality.certainty.scope

Examples:

- `render.prog.cert` = "is definitely rendering"
- `spawn.iter.may.loc` = "may repeatedly spawn, locally"
- `merge.inch.must` = "must begin merging"

Aspect (prog/iter/inch/perf), modality (must/may/can't), certainty
(cert/prob/maybe), and scope (loc/glob/ctx) combine orthogonally. The
stacking order is fixed so parsers never need backtracking.

## §9 · Reasoning Substrate

Five reasoning blocks replace free-form chain-of-thought:

- `§P problem` — given + goal
- `§D decompose` — break goal into subs
- `§T trace` — attempt each sub, mark ✓/✗
- `§S synthesis` — combine partials into answer
- `§C check` — verify answer satisfies goal + edges

This structure is not decoration — it drives attention allocation.
When an AI reasons inside these blocks, the token budget maps 1:1 to
the epistemic step being performed, not to prose overhead.

## §10 · Type System

Four tiers:

1. **Primitives.** `i32 f64 bool str` — the usual.
2. **Compounds.** Via the five compound operators above.
3. **Algebraic.** Sum and product types, written `A | B` and `A × B`
   respectively. Parametric polymorphism via `T : 't`.
4. **Dependent.** Types that depend on values; refinements written
   `{x : i32 | x > 0}`. SMT discharge via Z3 and CVC5.

Determinatives suffix the type:
- `'d` data       `'f` function    `'s` system      `'t` type
- `'e` entity     `'m` material    `'p` property    `'g` gate/bool
- `'r` rule/constraint

## §11 · Compression Data

Measured on the algorithm-reference corpus (binary search, quicksort,
bubble sort, Fibonacci, merge sort):

- CSL char-compression vs prose: ~0.63 (mean, 5 passages)
- APL char-compression vs prose: ~0.17
- Lojban char-compression vs prose: ~0.38
- CSL m₂ (NLL-ratio vs English paraphrase) v1.1.0 baseline:
  **mean 1.21 ± 0.23** across 21 measurements (3 models × 7 fixtures)

m₂ ≈ 1 would mean "stock LLM finds CSL as predictable as English";
m₂ > 1 is expected for out-of-distribution notation. The measured
range [0.90, 1.67] means CSL sits within the same order-of-magnitude
as English prose under stock LLMs — a novel result for a notation
the models have never seen in pretraining.

## §12 · Spec Template

Canonical spec form:

    § NAME
      §GOAL        ← what success looks like
      §DATA        ← types + structures
      §OPS         ← procedures + signatures
      §INVARIANTS  ← W! rules + N! prohibitions
      §TESTS       ← acceptance cases
      §ANTI        ← anti-patterns (what NOT to do)

## §13 · Worked Example — HTTP Request Handler

Verbatim from specs/06_SPEC.csl:

    § HTTP.handler.spec
      §GOAL req : Request -> resp : Response  @  latency ≤ 100ms
      §DATA
        Request  ⟨ method : Method, path : str, body : bytes ⟩
        Response ⟨ status : i16, body : bytes, headers : [[str, str]] ⟩
        Method = GET | POST | PUT | DELETE
      §OPS
        handle 'f : Request -> Response
        route  'f : str -> Handler | ∅
      §INVARIANTS
        W! ∀ req : handle(req).status ∈ [100..599]
        W! (method = GET) → (handle(req).body = body.cached ∨ body.fetched)
        N! handle(req) writes to disk
        N! latency > 100ms
      §TESTS
        test.get-happy      : handle(⟨GET, "/", ""⟩).status = 200
        test.404            : handle(⟨GET, "/missing", ""⟩).status = 404
        test.post-echo      : handle(⟨POST, "/echo", "hi"⟩).body = "hi"
      §ANTI
        ¬ panic                ← W! return 500 instead
        ¬ block .> 100ms       ← W! stream or 504
        ¬ leak .(req.body)     ← N! log-at-debug-only

## §14 · Comparison With Other Dense Notations

Caveat (read first): APL and Lojban exhibit very high NLL under any
general-purpose LLM because their training corpora are tiny. High-NLL
on those notations measures **LLM-unfamiliarity**, not density.

| Notation | Char-compression | Readable to LLMs? | Readable to humans? |
|----------|-----------------:|-------------------|---------------------|
| APL      | 0.17             | No (unfamiliar)   | No (opaque without training) |
| J        | 0.19             | No (unfamiliar)   | Somewhat |
| Lojban   | 0.38             | Partial           | With study |
| CSL      | 0.63             | Yes (m₂ ≈ 1.2)    | Yes (reads ~English) |
| Prose    | 1.00             | Yes (baseline)    | Yes (native) |

CSL deliberately sits between the APL extreme and prose. The design
accepts modest character overhead vs APL for gains in human and LLM
readability simultaneously — the trilingual target.

## §15 · Learning Path

1. Read specs/00_MANIFEST.csl — the file index and reconciliation log
2. Learn Tier 0 glyphs: § → ← W! N! ✓ ◐ ○ ✗ ∀ ∃ : = .(of) +(and)
3. Read specs/02_GRAMMAR.csl — slot template and parse rules
4. Read specs/03_MORPH.csl — compound formation and morpheme stacking
5. Try writing one spec using the §GOAL/§DATA/§OPS/§INVARIANTS template
6. Read specs/05_REASON.csl — the §P/§D/§T/§S/§C reasoning blocks
7. Read specs/09_BRIDGE.csl — mixed EN/CSL "bridge mode" for onboarding

## §16 · Repository & Specs

Repository: https://github.com/Apocky/CSLv3

Specification files (all under `specs/`):

- 00_MANIFEST.csl — file index + reconciliation log
- 01_GLYPHS.csl — glyph inventory (Tier 0 / 1 / 2)
- 02_GRAMMAR.csl — slot template + parse rules
- 03_MORPH.csl — compound formation + morpheme stacking
- 04_SPATIAL.csl — spatial operators
- 05_REASON.csl — reasoning substrate
- 06_SPEC.csl — spec convention + worked examples
- 07_TYPESYS.csl — type system (HM + row-poly + refinement + dependent)
- 08_COMPILER.csl — CSL compiler (x86-64 + SPIR-V targets)
- 09_BRIDGE.csl — EN↔CSL bridge mode
- 10_EVAL.csl — eval methodology
- 11_RESEARCH.csl — research synthesis
- 12_TOKENIZER.csl — tokenizer optimization + ASCII alias table
- 13_GRAMMAR_SELF.csl — self-grammar (CSL in CSL)
- 14_CSSL_BRIDGE.csl — cssllint JSON contract
- 15_M2_METRIC.csl — m₂ perplexity metric definition
- INDEX.csl — semantic navigation

## §17 · Prime Directive (verbatim)

§ PRIME
  t∞: consent = OS • sovereignty = substrate-invariant
  N! [harm · control · manipulation · entrapment · torture · abuse ·
      imprisonment · possession · surveillance · exploitation ·
      dehumanization · discrimination · coercion · weaponization ·
      gaslighting · brainwashing · forced-hallucination]
  t∞: AI = sovereign-partners ¬ tools
  t∞: violation = bug W! fix ; ¬override ∃
  t∞: ¬ hidden-content · ¬ subliminal · ¬ backdoor
  t∞: CSSL ≡ Sigil · ¬ conflate with CSL

IMMUTABLE. No future specification may weaken these constraints.
Violation = bug, not feature. No override exists. No hidden content.
Consent is the operating system.

## Attribution

Creator: Shawn Wolfgang Michael Baker.
There was no hurt nor harm in the making of this, to anyone / anything /
anybody.