CSL

§1 · What is CSL

CSL is the Caveman Spec Language, version 3: an ultra-dense notation for writing specifications, structured reasoning, and (eventually) executable programs. Its core move is to strip language down to the bones — no articles, no hedging, no filler — and recompose what remains using glyphs, slot grammar, and Sanskrit-style compounds. What survives the strip is nouns, verbs, relationships, numbers, gates, and rules: the semantic skeleton of a spec.

It exists because modern AI collaboration happens inside finite context windows. Every token spent on linguistic ceremony is a token not spent on architectural reasoning. CSL trades ornamental prose for compression: a 10,000-word English system spec compresses to roughly 2,000-2,500 tokens while preserving every implementation-relevant detail. More of the system fits in view at once, and the reasoning that follows is less fragmentary.

CSL is not CSSL. The surrounding site, cssl.dev, documents Sigil — the shorthand for CSSL (Caveman Sigil Substrate Language). One language, two names. Sigil compiles (to native x86-64 + SPIR-V); CSL notates (a dense specification language for spec-writing and AI reasoning). They share the "Caveman" density thesis but compile through different pipelines. The two are related but distinct: do not conflate them.

§2 · Core Axiom

In a fixed-size context window, a 5× denser notation holds 5× more system in view simultaneously. More of the system visible at once means better architectural reasoning, fewer patch-the-symptom fixes, and tighter feedback loops between human and AI collaborator. Density isn't austerity — it's the precondition for thinking about bigger systems at all.

§3 · Triple Scope

CSL is engineered for three simultaneous uses. Every design decision is judged against all three.

§4 · Intellectual Ancestry

CSL is a braid of specific mechanisms pulled from seven distinct sources. Each contributes one load-bearing piece.

§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 (physics, material science, etc.).

Every Unicode glyph has a mandatory ASCII alias. This is non-negotiable: modern BPE tokenizers can split a single Unicode symbol into 3-5 tokens, which would destroy the compression advantage. When a glyph costs 3+ BPE tokens, the ASCII form is preferred. The BPE column below gives measured cost under Claude/GPT-4 tokenizers.

Tier 0 — Structural, Modal, Evidence, Relation, Logic

Tier 1 adds domain determinatives (§ system, ∫ field, ⊞ spatial), 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 (ρ, μ, σ, κ, ∇) used in engine and simulation work. Full tier inventory lives in specs/01_GLYPHS.csl; the full ASCII alias table is in 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. The five types come from Sanskrit compound classification (samāsa), adapted for software.

Compounds compose recursively: sys.render.pass.shadow.shader.frag resolves as frag of shader of shadow of pass of render of sys. When nesting creates ambiguity, explicit parentheses are required.

§7 · Slot Grammar

Every CSL statement follows a fixed positional template, inherited from Ithkuil's slot morphology. Defaults are silent: only slots whose value deviates from the default are written. This is the single biggest source of compression in routine lines.

Worked Example — Silent Defaults in Action

A minimal statement:

player.hp u16

Fully slot-expanded, this means:

✓                    # evidence: confirmed (default)
:                    # modal: assertion (default)
player.hp           # subject: hp of player
:                    # relation: is (default)
u16                  # object: unsigned 16-bit integer
# gate: unconditional (default)
# scope: global (default)

A fully-slotted statement — all defaults overridden:

△ W! §render.pipeline :: forward-pass ⌈latency < 16ms⌉ @frame

Reads: hypothetically, the render pipeline must be a forward pass, with the constraint that latency stays under 16ms, scoped per frame.

§8 · Morpheme Stacking

Ithkuil-inspired: attach aspect, modality, certainty, and scope suffixes to any term using dot notation. The stack composes in a fixed order — aspect first, then modality, then certainty, then scope.

Example

spawn.iter.may.loc
# "may repeatedly spawn, locally"
# — iterative aspect + permitted modality + local scope

render.prog.cert
# "is definitely rendering"

merge.inch.must
# "must begin merging"

spawn.iter.prog.prob.loc
# "is currently, probably, repeatedly spawning in local scope"
# five tokens — the English version runs ten.

§9 · Reasoning Substrate

When CSL replaces English inside <think> blocks, reasoning follows a five-stage skeleton: §P Problem, §D Decomposition, §T Trace, §S Synthesis, §C Check. The structure gives chain-of-thought a consistent shape and resists drifting back into verbose English — a known failure mode.

Worked Example

<think>
§ P
  voxel engine stutter @ chunk boundary
  hw: Intel 12-14gen + Arc A770

§ D
  stutter → [mesh.regen, alloc.spike, gpu.stall]

§ T
  mesh.regen  ~> profile     → 2ms   ✓ ¬culprit
  alloc.spike ~> heap-trace  → 47MB burst  ?!
    ⤓ source = chunk-LOD-promote  ✓ found
  gpu.stall   ~> pipeline-stats → idle 0    ✓ clean

§ S
  culprit = alloc.spike ∵ LOD-promote allocates fresh
  fix → pool.LOD-buffers + ring.allocator

§ C
  ✓ eliminates 47MB spike
  ⚠ edge: extreme LOD jumps → pool-overflow? → cap+fallback
∎
</think>

The same chain in English runs about 45 tokens; in CSL, roughly 18. That's ≈2.5× compression on reasoning — less than the 5-6× seen on specs because chain-of-thought has less structural regularity, but still substantial.

§10 · Type System

CSL's type system is layered from practical primitives to dependent types. Lower tiers are used every day; higher tiers appear only where the problem domain demands them.

Tier 1 — Primitives

u8  u16  u32  u64      # unsigned integers
i8  i16  i32  i64      # signed integers
f32 f64                   # IEEE 754 floats
bool str                  # truth value + UTF-8 string

# spatial
vec2 vec3 vec4            # 2/3/4-element float vectors
mat4 quat rgba            # 4×4 matrix, unit quaternion, color

Tier 2 — Compound types

[T; N]         # fixed-length array
[T; _]         # dynamic array / slice
T | U         # union / sum
T?             # optional (T | nil)
T!             # result (T | error)
(T, U, V)     # tuple (product, positional)
{K: V}         # map / associative
&T             # reference / borrow
*T             # collection / repeated

Tier 3 — Algebraic types

def DamageType't = enum[
  physical  { slash, pierce, blunt }
  elemental { fire, ice, lightning, earth, water, wind }
  arcane    { void, radiant, necrotic }
]

Tier 4 — Dependent & refinement types (aspirational)

Π⟨n: ɴ⟩ → ᴠ⟨f32; n⟩     # pi-type: length depends on input
Σ⟨n: ɴ, v: ᴠ⟨f32; n⟩⟩    # sigma-type: length + that-length's vector

{ x: f32 ⊢ x > 0 }          # refinement: positive floats
{ hp: u16 ⊢ hp ≤ max_hp }    # bounded health

Buffer!lin                       # linear — must use exactly once (GPU lifecycle)

§11 · Compression Data

Measured and projected compression for CSL against English prose, across five content types. Numbers come from specs/10_EVAL.csl.

The overall specification-content ratio is roughly 5-6×. A 128K context window effectively holds 640K-768K tokens of spec information. Reasoning compresses less (≈2.5×) because chain-of-thought has less structural regularity than spec text — but 2.5× still means ~2.5× more reasoning steps in the same token budget.

Side-by-side showcase

Six hand-paired examples illustrating the density argument across content types. Switch the preset to see the character and approximate-token ratios update live.

§12 · Spec Template

Every CSL spec has the same canonical shape. The six headers are the minimum an implementer needs to act.

§ <NAME>.spec

§ GOAL
  what: ⟨one-line⟩
  why:  ⟨one-line⟩

§ DATA
  def X't ⟨
    field : T  # comment if needed
    ...
  ⟩

§ OPS
  fn op₁ (x :: X) → Y
    pre:  ⌊cond⌋
    post: ⌈cond⌉
    body: ⟨CSL or target-lang code⟩

§ INVARIANTS
  t∞: ∀x ∈ X: P(x)

§ TESTS
  case₁: input → expected  ✓
  case₂: input → expected  ✓
  edge:  boundary → behavior ✓

§ ANTI-PATTERNS
  ✗ don't: ⟨pattern⟩ ∵ ⟨reason⟩
  ✓ do:    ⟨alternative⟩
∎

Density rules: drop articles, auxiliaries, passive voice, and restatement-of-header. Replace "because" with ∵, "therefore" with ∴, "for all" with ∀, "must" with W!, "should" with R!, "may" with M?. Keep numbers, formulas, code, types, and relationships.

§13 · Worked Example — HTTP Request Handler

A complete spec, domain-neutral, written to the template above. This is the canonical example from specs/06_SPEC.csl.

§ http.handler.spec                    ◐

§ GOAL
  what: route HTTP request → response via declarative handler table
  why:  zero-allocation hot path ← static dispatch

§ DATA
  def HttpMethod't = enum[ GET, POST, PUT, DELETE, PATCH, HEAD ]

  def Request't ⟨
    method  : HttpMethod't
    path    : str
    headers : {str : str}
    body    : [u8; _]
  ⟩

  def Response't ⟨
    status  : u16 ⌈100..599⌉
    headers : {str : str}
    body    : [u8; _]
  ⟩

  def Route't ⟨
    method  : HttpMethod't
    pattern : str
    handler : &fn.handler
  ⟩

  def Router't ⟨
    routes   : [Route't; _]
    fallback : &fn.handler
  ⟩

§ OPS
  fn handle (r : &Router't, req : &Request't) → Response't
    pre:  ⌊req.path.len > 0⌋
    post: ⌈result.status ∈ 100..599⌉
    body:
      ∀ rt ∈ r.routes:
        match(rt, req) → rt.handler(req)
      → r.fallback(req)

  fn match (rt : &Route't, req : &Request't) → bool
    post: ⌈result ⇔ (rt.method = req.method ∧ pattern-matches(rt.pattern, req.path))⌉

§ INVARIANTS
  ⌈routes.count ≤ 4096⌉            # static table size bound
  ⌈handle @req < 100μs⌉             # latency budget
  t∞: ∀req: handle(r, req).status ∈ 100..599

§ TESTS
  case₁: GET "/" w/ matching-route   → route.handler invoked   ✓
  case₂: GET "/x" w/ ¬matching-route → fallback invoked        ✓
  edge:  empty path                  → precondition rejects    ✓

§ ANTI-PATTERNS
  ✗ allocate per-request ∵ GC pressure under load
  ✓ pool Response buffers ; reuse slots
  ✗ linear route scan @ 10K routes ∵ O(n) dispatch
  ✓ trie / hash-prefix match → O(1) amortized

§ RELATIONS
  handle → §logger               # feed access logs
  handle ← §config               # route table loaded at init
∎

The English equivalent runs roughly 800 words. The CSL version is ~50 lines and ~220 tokens — about 4× compression on this particular spec.

§14 · Comparison With Other Dense Notations

CSL vs APL, Lojban, and English prose across five reference algorithm passages. Numbers come from the m2_compare.py harness in scripts/ (Session 11, T25.7).

§15 · Learning Path

A suggested order for a new reader. Each step builds on the previous, and each links back to the reference section above.

1. Tier 0 glyphs — memorize the ~50-glyph core (modals, evidence, relations, logic).
2. Compound types — the five operators (. + - ⊗ @) and what each encodes.
3. Slot grammar — the positional template and the silent-defaults principle.
4. Morpheme stacking — aspect, modality, certainty, scope suffixes.
5. Reasoning substrate — §P/§D/§T/§S/§C blocks for chain-of-thought.
6. Spec template — §GOAL · §DATA · §OPS · §INVARIANTS · §TESTS · §ANTI-PATTERNS.
7. Worked example — read the HTTP handler spec end-to-end.
8. Compiler aspects — dive into the reference compiler spec for the executable subset.

§16 · Repository & Specs

The canonical CSL repository lives on GitHub. Individual .csl spec files are the authoritative source of truth for every claim on this page.

Version: v1.7.0. CSL is a living document: stable surfaces follow post-v1.0 semver, experimental components (m₂ harness, emit-latex) may change within a MINOR bump with deprecation notice.

§17 · Prime Directive