Seq - Concatenative Language

A concatenative, stack-based programming language that compiles to native executables. Seq combines the elegance of stack-based programming with a sophisticated type system, guaranteed tail call optimization, and CSP-style concurrency.

Home Code Repository is at git.navicore.tech

PRs and issues welcome at codeberg.org mirror

Documentation

Naming guide: The GitHub repository is patch-seq. On crates.io, the packages are published as seq-compiler, seq-repl, and seq-lsp. Once installed, the binaries are seqc, seqr, and seq-lsp.

: factorial ( Int -- Int )
  dup 1 i.<= if
    drop 1
  else
    dup 1 i.- factorial i.*
  then
;

: main ( -- ) 10 factorial int->string io.write-line ;

Project Status

Stable as of 4.0. The language and standard library are stable and used by the creators for their own projects. That said, Seq is a niche experimental language - adopt it with eyes open. Future versions follow strict semantic versioning: major version increments indicate breaking changes to the language or standard library. Minor and patch versions add features and fixes without breaking existing code.

Why Seq?

Stack-based simplicity. No variable declarations, no argument lists - values flow through the stack. Code reads left-to-right as a pipeline of transformations.

Strongly typed with effect tracking. Stack effects aren’t just comments - they’re enforced by the compiler. The type system tracks not only what goes on and off the stack, but also side effects like yielding from generators:

: counter ( Ctx Int -- | Yield Int )   # Yields integers, takes a context
  tuck yield        # yield current count, receive resume value
  drop swap 1 i.+ counter
;

Guaranteed tail call optimization. Recursive functions run in constant stack space via LLVM’s musttail. Write elegant recursive algorithms without stack overflow concerns.

CSP-style concurrency. Lightweight strands (green threads) communicate through channels. No shared memory, no locks - just message passing.

No implicit numeric conversions. Operations like i.+ and f.+ make types explicit. No silent coercion, no precision loss, no “wat” moments - when you need to mix types, you convert explicitly with int->float or float->int.

Installation

Prerequisites — clang is required to compile Seq programs (used to compile LLVM IR to native executables):

• macOS: xcode-select --install
• Ubuntu/Debian: apt install clang libedit-dev
• Fedora: dnf install clang

Install from crates.io:

cargo install seq-compiler
cargo install seq-repl
cargo install seq-lsp

This installs the following binaries:

Build from source:

cargo build --release

Virtual Environments — Create isolated environments to manage multiple Seq versions or pin a specific version for a project:

seqc venv myenv
source myenv/bin/activate

This copies the seqc, seqr, and seq-lsp binaries into myenv/bin/, completely isolated from your system installation. Unlike Python’s venv (which uses symlinks), Seq copies binaries so your project won’t break if the system Seq is updated.

Activate/deactivate:

source myenv/bin/activate   # Prepends myenv/bin to PATH, shows (myenv) in prompt
deactivate                  # Restores original PATH

Supports bash, zsh, fish (activate.fish), and csh/tcsh (activate.csh).

Quick Start

Compile and run a program:

seqc build examples/basics/hello-world.seq
./hello-world

Script mode (run directly):

seqc examples/basics/hello-world.seq          # Compile and run in one step

Scripts can use shebangs for direct execution:

#!/usr/bin/env seqc
: main ( -- Int ) "Hello from script!" io.write-line 0 ;

chmod +x myscript.seq
./myscript.seq arg1 arg2    # Shebang invokes seqc automatically

Script mode compiles with -O0 for fast startup and caches binaries in ~/.cache/seq/ (or $XDG_CACHE_HOME/seq/). Cache keys include the source and all includes, so scripts recompile automatically when dependencies change.

Check version:

seqc --version

Run tests:

cargo test --all

Learn Seq

New to concatenative programming? Start with the Glossary - it explains concepts like stack effects, quotations, row polymorphism, and CSP in plain terms.

Learn by doing: Work through seqlings - hands-on exercises that teach the language step by step, covering stack operations, arithmetic, control flow, quotations, and more. Each exercise includes hints and automatic verification.

Interactive REPL

The seqr REPL provides an interactive environment for exploring Seq:

seqr

Stack persists across lines:

seqr> 1 2
stack: 1 2
seqr> i.+
stack: 3
seqr> 5
stack: 3 5
seqr> : square ( Int -- Int ) dup i.* ;
Defined.
seqr> square
stack: 3 25

Commands: :clear (reset), :edit (open in $EDITOR), :pop (undo), :quit (exit), :show (show file), :stack (show stack)

Editing: Vi-mode (Esc for normal, i for insert), Shift+Enter (newline), Tab (completions), F1/F2/F3 (toggle IR views)

Language Features

Stack Operations & Arithmetic:

dup drop swap over rot nip tuck pick 2dup 3drop   # Stack manipulation
i.+ i.- i.* i./ i.%                               # Integer arithmetic
f.+ f.- f.* f./                                   # Float arithmetic
i.= i.< i.> i.<= i.>= i.<>                        # Comparisons
band bor bxor bnot shl shr popcount               # Bitwise operations

Numeric literals support decimal, hex (0xFF), and binary (0b1010).

Algebraic Data Types — Define sum types with union and pattern match with match:

union Option { None, Some { value: Int } }

: unwrap-or ( Option Int -- Int )
  swap match
    None ->
    Some { >value } -> nip
  end
;

Quotations & Higher-Order Programming — Quotations are first-class anonymous functions:

[ dup i.* ] 5 swap call    # Square 5 → 25
my-list [ 2 i.* ] list.map # Double each element

Concurrency — Strands (green threads) communicate through channels:

chan.make
dup [ 42 swap chan.send drop ] strand.spawn drop
chan.receive drop    # Receives 42

Weaves provide generator-style coroutines with bidirectional communication:

[ my-generator ] strand.weave
initial-value strand.resume   # Yields values back and forth

Standard Library — Import modules with include std:module:

Sample Programs

See the Examples chapter for complete programs organized by category (basics, language features, paradigms, data formats, I/O, projects, FFI).

Editor Support

The seq-lsp language server provides IDE features in your editor.

Install: cargo install seq-lsp

Neovim: Use patch-seq.nvim with Lazy:

{ "navicore/patch-seq.nvim", ft = "seq", opts = {} }

Features: Real-time diagnostics, autocompletion for builtins/local words/modules, context-aware completions, syntax highlighting.

Configuration

Environment Variables:

SEQ_STACK_SIZE=262144 ./my-program       # 256KB stacks
SEQ_YIELD_INTERVAL=10000 ./my-program    # Yield every 10K tail calls
SEQ_WATCHDOG_SECS=30 ./my-program        # Warn if strand runs >30s
SEQ_REPORT=1 ./my-program                # Print KPI report on exit

Compile with --instrument for per-word call counts in the report:

seqc build --instrument my-program.seq
SEQ_REPORT=1 ./my-program                # Report includes word call counts

License

MIT

Seq Language Guide

A concatenative language where composition is the fundamental operation.

Why Concatenative?

If you’ve written Rust like this:

#![allow(unused)]
fn main() {
data.iter()
    .map(transform)
    .filter(predicate)
    .fold(init, combine)
}

You’ve already experienced the appeal of concatenative thinking: data flows through a pipeline, each step consuming its input and producing output for the next. No intermediate variables, no naming - just composition.

Seq takes this idea to its logical conclusion. Where Rust uses method chaining as syntactic sugar over function application, Seq makes composition the only mechanism:

data [ transform ] list.map [ predicate ] list.filter init [ combine ] list.fold

The connection runs deeper than syntax. Rust’s FnOnce trait means “callable once, consumes self.” Seq’s stack semantics mean “pop consumes the value.” Both enforce linear dataflow - resources used exactly once. Rust tracks this in the type system; Seq tracks it through the stack.

Language Heritage

Seq belongs to the concatenative language family. If you know Forth or Factor, you’ll feel at home:

Syntactically, Seq is ~80% Forth, ~15% Factor - a Forth programmer reads Seq immediately; a Factor programmer feels at home with the quotations and type annotations.

Semantically, Seq is novel:

• Row-polymorphic type system - Forth is untyped; Factor has optional inference. Seq statically verifies stack effects with full type checking.

• CSP concurrency - Neither Forth nor Factor has built-in green threads with channels. Seq’s spawn, send, and receive enable actor-style concurrency.

• LLVM compilation - Seq compiles to native binaries via LLVM, not threaded code or a VM.

Seq wears familiar Forth clothes while offering modern type safety and concurrency. It’s a new language built on proven concatenative foundations.

The Stack

Everything in Seq operates on an implicit stack. Literals push values; words consume and produce values:

1 2 i.+    # Push 1, push 2, add consumes both, pushes 3

The stack replaces variables. Instead of:

let x = 1
let y = 2
let z = x + y

You write:

1 2 i.+

The stack is your working memory.

Words

Words are the building blocks. A word is a named sequence of operations:

: square ( Int -- Int )
  dup i.*
;

The ( Int -- Int ) is the stack effect - this word consumes one integer and produces one integer. Stack effects are required on all word definitions - the compiler verifies that the body matches the declared effect.

Calling a word is just writing its name:

5 square    # Result: 25

Quotations

Quotations are deferred code - blocks that can be passed around and executed later:

[ 2 i.* ]    # Pushes a quotation onto the stack

Quotations enable higher-order programming:

5 [ 2 i.* ] call    # Result: 10

They’re essential for combinators like list.map, list.filter, and control flow.

Control Flow

Conditionals use stack-based syntax:

condition if
  then-branch
else
  else-branch
then

The condition is popped from the stack and must be a Bool (produced by comparisons, true/false literals, or logical operations):

: abs ( Int -- Int )
  dup 0 i.< if
    0 swap i.-    # negate: 0 - n
  then
;

Values and Types

Seq has these value types:

Numeric Literals

Integers can be written in decimal, hexadecimal, or binary:

42          # Int (decimal)
-123        # Int (negative)
0xFF        # Int (hexadecimal, case insensitive: 0xff, 0XFF)
0b1010      # Int (binary, case insensitive: 0B1010)

Floats use decimal notation with a decimal point:

3.14        # Float
-0.5        # Float (negative)

Stack Operations

The fundamental stack manipulators:

Master these and you can express any data flow without variables.

Composition

The key insight: in Seq, juxtaposition is composition.

: double  2 i.* ;
: square  dup i.* ;
: quad    double double ;    # Composition by juxtaposition

Writing double double doesn’t “call double twice” in the applicative sense - it composes two doublings into a single operation.

Since a word is just a named sequence of operations, any contiguous sequence can be extracted into a new word without changing meaning:

# Given words a, b, c, d in sequence:
a b c d

# Define a new word for "b c":
: bc  b c ;

# This is equivalent:
a bc d

A concrete example:

# Four words in sequence
read parse transform write

# Extract middle two into a word
: process  parse transform ;
read process write          # Same behavior

Comments

Comments start with # and continue to end of line:

# Whole-line comment

5 square  # Inline comment after code

I/O Operations

Basic console I/O:

Line Ending Normalization

All line-reading operations (io.read-line, file.for-each-line) normalize line endings to \n. Windows-style \r\n is converted to \n. This ensures Seq programs behave consistently across operating systems.

Handling EOF with io.read-line

The io.read-line word returns a success flag, making EOF handling explicit:

io.read-line    # ( -- String Bool )
                # Success: ( "line\n" true )
                # EOF:     ( "" false )

Example - reading all lines until EOF:

: process-input ( -- )
    io.read-line if
        string.chomp    # Remove trailing newline
        process-line    # Your processing word
        process-input   # Recurse for next line
    else
        drop            # Drop empty string at EOF
    then
;

Algebraic Data Types (ADTs)

Seq provides compile-time safe algebraic data types with union definitions and match expressions.

Seq’s union is similar to Rust’s enum - each variant can carry multiple named fields. This differs from C++’s std::variant, where each alternative holds only a single type.

Union Definitions

Define sum types with typed fields:

union Option { Some { value: Int }, None }

union Message {
  Get { response-chan: Int }
  Increment { amount: Int }
  Report { op: Int, delta: Int, total: Int }
}

The compiler automatically generates typed constructors:

• Make-Some: ( Int -- Option )
• Make-None: ( -- Option )
• Make-Get: ( Int -- Message )
• Make-Report: ( Int Int Int -- Message )

Compile-Time Safety

The compiler catches common errors:

Field type validation - Only valid types allowed:

union Bad { Foo { x: Unknown } }  # Error: Unknown type 'Unknown'

Valid field types: Int, Float, Bool, String, or another defined union.

Variant arity limit - Maximum 12 fields per variant:

union TooBig { V { a: Int, b: Int, c: Int, d: Int, e: Int, f: Int,
                   g: Int, h: Int, i: Int, j: Int, k: Int, l: Int, m: Int } }
# Error: Variant 'V' has 13 fields, maximum is 12.
# Consider using a Map or grouping fields into nested union types.

Pattern Matching

Use match to destructure variants. The compiler requires exhaustive matching:

: describe ( Option -- String )
  match
    Some { >value } -> drop "has value"   # drop the extracted value
    None -> "empty"
  end
;

Non-exhaustive matches are compile errors:

: bad ( Option -- String )
  match
    Some -> "has value"
    # Error: Non-exhaustive match on 'Option'. Missing variants: None
  end
;

Stack-Based Matching

All fields are pushed to stack in declaration order:

: handle ( Message -- )
  match
    Get ->              # ( response-chan )
      send-response
    Increment ->        # ( amount )
      do-increment
    Report ->           # ( op delta total )
      drop nip          # extract delta
      process
  end
;

Named Bindings

Request specific fields by name using > prefix (indicating stack extraction, not variable binding):

: handle ( Message -- )
  match
    Get { >response-chan } ->
      # response-chan is now on stack
      send-response
    Increment { >amount } ->
      # amount is now on stack
      do-increment
    Report { >delta } ->     # only 'delta' pushed to stack
      process
  end
;

The > prefix makes clear these are stack extractions, not local variables. Both styles compile to identical code. Mix them freely.

ADTs with Row Polymorphism

ADTs and row polymorphism are orthogonal:

union Option { Some { value: Int }, None }

# Row polymorphic - extra stack values pass through
: unwrap-or ( ..a Option Int -- ..a Int )
  swap match                    # swap so Option is on top for match
    Some { >value } -> nip      # remove default, keep extracted value
    None ->                     # keep default
  end
;

"hello" 42 Make-Some 0 unwrap-or   # ( "hello" 42 )

Low-Level Variants

For dynamic use cases, low-level primitives create tagged values at runtime. A variant is a value with a symbol tag (like :Some or :Nil) and zero or more fields.

Creating Variants

The variant.make-N words take N values from the stack plus a symbol tag:

The tag is always the last argument (top of stack):

:None variant.make-0              # Creates: (None)
42 :Some variant.make-1           # Creates: (Some 42)
"x" 10 :Point variant.make-2      # Creates: (Point "x" 10)

Inspecting Variants

"x" 10 :Point variant.make-2    # ( Point )
dup variant.tag                 # ( Point :Point )
drop 0 variant.field-at         # ( "x" )

Cons Lists (Lisp-Style Linked Lists)

A cons list is a classic linked list from Lisp. Each node is either:

• Nil: empty list (no fields)
• Cons: a pair of (first-element, rest-of-list)

The names come from Lisp heritage:

• cons = “construct” a pair
• car = “contents of address register” = first element
• cdr = “contents of decrement register” = rest of list

Here’s the complete pattern:

# Constructors
: nil ( -- List )  :Nil variant.make-0 ;
: cons ( T List -- List )  :Cons variant.make-2 ;

# Predicates
: nil? ( List -- Bool )  variant.tag :Nil symbol.= ;

# Accessors
: car ( List -- T )  0 variant.field-at ;
: cdr ( List -- List )  1 variant.field-at ;

Building a list works from right to left - start with nil, then prepend each element:

nil                   # ()           - empty list
3 swap cons           # (3)          - prepend 3
2 swap cons           # (2 3)        - prepend 2
1 swap cons           # (1 2 3)      - prepend 1

The swap is needed because cons expects ( T List ) but we have ( List T ).

In the REPL, the raw stack output for nested variants looks cryptic. Peek at elements without destroying the list:

dup car           # 1 - first element
dup cdr car       # 2 - second element
dup cdr cdr car   # 3 - third element

See examples/data/cons-list.seq for a complete example with length, reverse, and printing.

Safety Philosophy

Seq aspires to Rust’s core principle: if it compiles, it tends to run correctly. The compiler statically eliminates entire categories of bugs that cause runtime failures in other languages.

What the Compiler Guarantees

No Null

Seq has no null. There’s no implicit “absence of value” that can appear in any type.

When you need to represent optional or fallible values, use union types:

union Option { None, Some { value: Int } }
union Result { Ok { value: Int }, Err { message: String } }

If a function returns a union type, the compiler requires callers to handle all variants via exhaustive match. You cannot forget the error case:

: maybe-parse ( String -- Option )  ... ;

: use-it ( String -- Int )
  maybe-parse match
    None -> 0                    # must handle this
    Some { >value } ->           # value extracted to stack, returned as result
  end
;

This is opt-in. Seq doesn’t enforce a pervasive Result convention across the standard library - union types are used case by case where they make sense. The compiler’s role is to ensure that if you use a union type, callers must handle all variants.

What the Compiler Does Not Catch

Seq is not Rust. Some things remain the programmer’s responsibility:

The philosophy: eliminate the bugs that are both common and mechanically detectable. Stack effects catch most “wrong number of arguments” bugs. Exhaustive matching catches “forgot the error case.” No null catches “didn’t check for absence.” Explicit numerics catch “mixed up int and float.”

What remains are bugs that require understanding intent - and those are for tests and code review.

Value Semantics

Seq has straightforward value semantics with no ownership tracking or move semantics.

No Borrowing, No Moves

Unlike Rust, Seq has no borrow checker or ownership system. Unlike C++11+, there are no move constructors or rvalue references. Values are simply copied when needed:

5 dup    # Copies the integer - both stack positions hold 5

This simplicity comes from two design choices:

1. Values are immutable - you don’t mutate values, you create new ones
2. Sharing via reference counting - complex types use Arc internally for O(1) copying

Copying Behavior by Type

Why This Works

The lack of mutation eliminates the problems that borrowing solves. In Rust, you need the borrow checker because:

• Mutable references could alias
• Data could be freed while references exist
• Race conditions on shared mutable state

Seq sidesteps all of this:

• No mutation of values on the stack
• Reference counting handles lifetimes automatically
• Strands communicate via channels, not shared memory

Comparison to Other Languages

Seq’s model is closest to functional languages with persistent data structures. The simplicity cost is that large maps are expensive to “modify” (you clone the whole thing). The benefit is that you never think about lifetimes, borrows, or use-after-free.

Error Handling

Seq uses a simple, type-preserving pattern for fallible operations: ( value Bool ).

The Value-Bool Pattern

Operations that can fail return their result plus a Bool success flag:

"42" string->int    # ( -- 42 true ) on success
"abc" string->int   # ( -- 0 false ) on failure

This pattern is used consistently across the standard library:

Using the Pattern

The idiomatic way to handle fallible operations:

"42" string->int if
  # Success - the Int is on the stack
  2 i.*    # use it
else
  drop     # discard the failure value
  0        # provide a default
then

Chaining Fallible Operations

For multiple fallible operations, check each result:

: get-port ( -- Int Bool )
    # Get PORT from environment, parse it, validate range
    # Demonstrates chaining: getenv -> parse -> validate
    "PORT" os.getenv if                     # Check env var exists
      string->int if                        # Parse as integer
        dup 1024 i.>= over 65535 i.<= and if
          true                              # Valid port in range
        else
          drop 8080 false                   # Port out of range
        then
      else
        drop 8080 false                     # PORT is not a number
      then
    else
      drop 8080 false                       # PORT not set
    then
;

Why Not Result/Option Types?

Seq prioritizes compile-time type safety. A generic Result<T,E> type would require either losing type information (everything becomes Variant) or generic/parametric types (not supported).

The ( value Bool ) pattern preserves types: the Int stays an Int, the String stays a String.

If you need functional composition patterns (map, bind), you can define your own concrete Result types - see examples/paradigms/functional/result.seq for an example.

String Operations

Bitwise Operations

For low-level bit manipulation.

Int is 63-bit. Seq’s Int is a signed 63-bit integer — the low bit of the tagged stack slot is the type tag, leaving 63 bits for the value. Range: [-2^62, 2^62 - 1] = [-4611686018427387904, 4611686018427387903]. All bitwise operations report results in this 63-bit model. shl/shr results that would fall outside the range return 0 rather than silently truncating bit 62 in the tagger.

Shift Behavior

• Shift by 0 returns the original value.
• Shift by a negative count returns 0.
• Shift by 64 or more returns 0.
• Any shift result that doesn’t fit in the 63-bit Int range also returns 0.
• Right shift is logical (zero-fill), not arithmetic (sign-extending).

1 61 shl    # 2305843009213693952  (= 2^61, fits in 63-bit range)
1 62 shl    # 0  (would be 2^62, one past the 63-bit max)
-1 2 shr    # 4611686018427387903  (= 2^62 - 1, the 63-bit max)
-1 1 shr    # 0  (would be 2^63 - 1, outside the 63-bit range)

Recursion and Tail Call Optimization

Seq has no loop keywords. Iteration is recursion:

# Count down
: countdown ( Int -- )
    dup 0 i.> if
        dup int->string io.write-line
        1 i.- countdown
    else
        drop
    then
;

# Process a list
: sum-list ( Variant -- Int )
    dup nil? if
        drop 0
    else
        dup car swap cdr sum-list i.+
    then
;

Guaranteed Tail Call Optimization

Seq guarantees TCO via LLVM’s musttail calling convention. Deeply recursive code won’t overflow the stack - you can recurse millions of times safely.

More importantly, Seq’s TCO is branch-aware. The compiler recognizes tail position within each branch of a conditional, not just at word level. This means you can write natural recursive code without restructuring for optimization:

: process-input ( -- )
    io.read-line if
        string.chomp
        process-line
        process-input   # Tail call - even inside a branch
    else
        drop
    then
;

In many languages, you’d have to “game” the compiler - inverting conditions, using continuation-passing style, or adding explicit trampolines to get TCO. In Seq, the compiler does this analysis for you. Write readable code; get optimization automatically.

When TCO Applies

TCO works for user-defined word calls in tail position. It does not apply in:

• main - entry point uses C calling convention
• Quotations [ ... ] - use C convention for interop
• Closures - signature differs due to captured environment

For hot loops that need guaranteed TCO, use a named word rather than a quotation:

# TCO works here
: loop ( Int -- )
    dup 0 i.> if
        1 i.- loop
    else
        drop
    then
;

Command Line Programs

: main ( -- )
    args.count 1 i.> if
        1 args.at          # First argument (0 is program name)
        process-file
    else
        "Usage: prog <file>" io.write-line
    then
;

Script Mode

For quick iteration and scripting, you can run .seq files directly without a separate build step:

seqc myscript.seq arg1 arg2

Script mode compiles with -O0 for fast startup and caches the binary for subsequent runs. The cache key includes the source content and all transitive includes, so scripts automatically recompile when any dependency changes.

Shebang Support

Scripts can include a shebang for direct execution:

#!/usr/bin/env seqc
: main ( -- Int ) "Hello from script!" io.write-line 0 ;

chmod +x myscript.seq
./myscript.seq arg1 arg2    # Arguments passed to main

Note that the main word in a script must return Int (the exit code), unlike compiled programs where main returns ( -- ).

Cache Location

Compiled binaries are cached in:

• $XDG_CACHE_HOME/seq/ if XDG_CACHE_HOME is set
• ~/.cache/seq/ otherwise

Cache entries are named by their SHA-256 hash. To clear the cache: rm -rf ~/.cache/seq/

When to Use Script Mode

Script mode trades runtime optimization (-O0) for faster compilation. For production use, compile with seqc build to get full LLVM optimizations.

File Operations

Directory Operations

Line-by-Line File Processing

For processing files line by line, use file.for-each-line:

: process-line ( String -- )
    string.chomp
    # ... do something with line
;

: main ( -- )
    "data.txt" [ process-line ] file.for-each-line
    if
        "Done!" io.write-line
    else
        "Error reading file" io.write-line
    then
;

The quotation receives each line (including trailing newline) and must consume it. Returns true on success (including empty files), false if the file could not be opened or a read error occurred mid-stream.

Line endings are normalized to \n regardless of platform - Windows-style \r\n becomes \n. This ensures consistent behavior when processing files across different operating systems.

This is safer than slurp-and-split for large files - lines are processed one at a time rather than loading the entire file into memory.

Modules

Split code across files with include:

# main.seq
include "parser"
include "eval"

: main ( -- )
    # parser.seq and eval.seq words available here
;

The include path is relative to the including file.

Naming Convention

Seq uses a consistent naming scheme for all built-in operations:

Words Are Just Names

In Seq, a word is any contiguous sequence of non-whitespace characters. There are no operators - the . in io.write-line is part of the word’s name, not syntax for “calling a method on an object.”

io.write-line    # This is ONE word, not "io" followed by "write-line"
string.concat    # This is ONE word, not a method call on a string object

If you come from object-oriented languages, this may feel strange at first. In OO, foo.bar means “send the bar message to foo.” In Seq, io.write-line is simply a name that includes a dot - exactly like write-line is a name that includes a hyphen. The dot is a naming convention for grouping related operations, not a dereferencing or method dispatch operator.

Concatenative languages work differently: there are no objects receiving messages. There is only the stack. Words consume values from the stack and push results back. io.write-line doesn’t operate “on” an io object - it pops a string and writes it.

Module Prefixes

Operations are grouped by functionality:

Names in Stack Effects

Three kinds of name appear inside ( ... -- ... ). They look similar but behave very differently — keep the distinction in mind, especially when writing or migrating word signatures.

: dup ( ..a T -- ..a T T )       # ..a = "anything below"; T = "any one type"
: net.tcp.write ( ..a String Socket -- ..a Bool )   # all named: row + concretes

Multi-character uppercase identifiers in stack effects must be a known concrete type or a registered union — Acc, Ctx, Handle etc. are not type variables. See TYPE_SYSTEM_GUIDE.md for the deeper “row polymorphism vs traditional generics” treatment, and GLOSSARY.md / Row Variable for one-line definitions.

Suffixes

Core Primitives (No Prefix)

Fundamental operations remain unnamespaced for conciseness:

• Stack: dup, swap, over, rot, nip, tuck, drop, pick, roll
• Boolean: and, or, not
• Bitwise: band, bor, bxor, bnot, shl, shr, popcount, clz, ctz
• Control: call, spawn, cond

Type-Prefixed Arithmetic and Comparison

Integer and float operations use explicit type prefixes:

• Integer arithmetic: i.add, i.subtract, i.multiply, i.divide (or terse: i.+, i.-, i.*, i./, i.%)
• Integer comparison: i.=, i.<, i.>, i.<=, i.>=, i.<> (or verbose: i.eq, i.lt, i.gt, i.lte, i.gte, i.neq)
• Float arithmetic: f.add, f.subtract, f.multiply, f.divide (or terse: f.+, f.-, f.*, f./)
• Float comparison: f.=, f.<, f.>, f.<=, f.>=

This is a deliberate design choice, not a limitation. Implicit type conversions are harmful.

Many languages silently convert between numeric types, leading to subtle bugs:

• JavaScript’s "5" + 3 yields "53" but "5" - 3 yields 2
• C silently converts between numeric types - promoting integers, truncating floats to integers, and losing precision when narrowing - without warning by default
• Python 2’s / behaved differently for int vs float operands

Seq rejects this entirely. When you write i.+, you know both operands are integers and the result is an integer. When you need to mix types, you convert explicitly:

42 int->float 3.14 f.+    # Explicit: convert int to float, then add

The code states exactly what happens. No implicit coercion, no surprises, no “wat” moments. The few extra characters buy certainty about program behavior.

Note that explicit conversions can still lose precision - int->float loses precision for integers beyond 2^53, and float->int truncates the fractional part. The point isn’t that conversions are lossless; it’s that you asked for it, and it’s visible in the code.

Rationale

The naming convention provides:

1. Discoverability - Related operations share a prefix. Wondering what you can do with strings? Look for string.*
2. No collisions - length could mean string length, list length, or map size. string.length, list.length, and map.size are unambiguous
3. Clean primitives - Core stack operations like dup and swap appear in nearly every word; namespacing them would add noise
4. Familiar patterns - The . delimiter echoes method syntax from other languages; -> for conversions is intuitive

Maps

Key-value dictionaries with O(1) lookup:

map.make                    # ( -- Map )
"name" "Alice" map.set      # ( Map K V -- Map )
"age" 30 map.set
"name" map.get              # ( Map K -- V Bool )
"name" map.has?             # ( Map K -- Map Bool )
map.keys                    # ( Map -- List )

SON (Seq Object Notation)

SON is Seq’s native data serialization format - it’s valid Seq code that reconstructs data when evaluated. This makes SON ideal for configuration files, data exchange, and debugging.

Format Overview

Using SON

Include the SON module to access builder words:

include std:son

# Build a list
list-of 1 lv 2 lv 3 lv          # ( -- List )

# Build a map
map-of "name" "Alice" kv        # ( -- Map )
       "age" 30 kv

# Build a variant (fields before tag)
:None wrap-0                    # ( -- Variant ) no fields
42 :Some wrap-1                 # ( -- Variant ) one field
10 20 :Point wrap-2             # ( -- Variant ) two fields

Serializing Values

Use son.dump to convert any value to its SON string representation:

include std:son

# Serialize primitives
42 son.dump                     # "42"
true son.dump                   # "true"
"hello" son.dump                # "\"hello\""

# Serialize complex structures
list-of 1 lv 2 lv son.dump      # "list-of 1 lv 2 lv"

# Pretty-print with indentation
list-of 1 lv 2 lv son.dump-pretty
# list-of
#   1 lv
#   2 lv

Loading SON Files

SON files define words that return data structures:

# config.son
include std:son

: config ( -- Map )
  map-of
    "debug" true kv
    "port" 8080 kv
;

# main.seq
include std:son
include "config.son"   # adds the 'config' word

: main ( -- )
  config              # call to get the Map
  "port" map.get      # get the port value
;

Stack Display

The REPL uses SON format when displaying stack contents via stack.dump:

stack: list-of 1 lv 2 lv map-of "name" "Alice" kv :None wrap-0 true 42

This makes it easy to copy values from the REPL output directly into Seq code.

Zipper: Functional List Navigation

The std:zipper module provides a zipper data structure for efficient cursor-based navigation and editing of immutable lists. A zipper maintains a focus element with left and right context, enabling O(1) movement and modification.

include std:zipper

# Create a zipper from a list
list-of 1 lv 2 lv 3 lv 4 lv 5 lv
zipper.from-list               # focus at 1

# Navigate
zipper.right zipper.right      # focus at 3

# Modify
99 zipper.set                  # replace focus with 99

# Convert back
zipper.to-list                 # [1, 2, 99, 4, 5]

Key operations:

• Navigation: zipper.left, zipper.right, zipper.start, zipper.end
• Query: zipper.focus, zipper.index, zipper.length
• Modification: zipper.set, zipper.insert-left, zipper.insert-right, zipper.delete

See STDLIB_REFERENCE.md for the complete API.

Higher-Order Words

# Map over a list
my-list [ 2 i.* ] list.map

# Filter a list
my-list [ 0 i.> ] list.filter

# Fold (reduce)
my-list 0 [ i.+ ] list.fold

Concurrency

Seq supports massive concurrency through strands - lightweight green threads built on a coroutine runtime. Thousands of strands can run on a single OS thread, cooperatively yielding during I/O operations.

Strands

Spawn a quotation as a new strand:

[ "Hello from strand!" io.write-line ] strand.spawn drop   # drop strand ID

Strands are cheap - spawn thousands of them. They’re ideal for:

• Handling concurrent connections
• Parallel processing pipelines
• Actor-style architectures

Channels (CSP-Style Communication)

Strands communicate through channels, following the CSP (Communicating Sequential Processes) model - similar to Go channels or Erlang message passing.

Channel operations return status flags rather than panicking. Always check the boolean result:

Producer-Consumer Example

: send-messages ( Channel Int -- )
    dup 0 i.> if
        over "message" swap chan.send drop  # send returns Bool, drop it
        1 i.- send-messages
    else
        drop chan.close
    then
;

: producer ( Channel -- )
    10 send-messages
;

: consumer ( Channel -- )
    dup chan.receive if
        io.write-line
        consumer        # loop via recursion
    else
        drop drop       # channel closed, drop message and channel
    then
;

: main ( -- )
    chan.make
    dup [ producer ] strand.spawn drop
    consumer
;

TCP Networking

Build network servers with strand-per-connection:

Concurrent Server Pattern

: handle-client ( Socket -- )
    dup net.tcp.read drop  # read request
    process-request        # your logic here
    over net.tcp.write drop # write response
    net.tcp.close drop
;

: accept-loop ( Socket -- )
    dup net.tcp.accept drop                  # ( listener client )
    [ handle-client ] strand.spawn drop      # spawn handler
    accept-loop                              # tail call - runs forever, no stack growth
;

: main ( -- )
    8080 net.tcp.listen
    "Listening on :8080" io.write-line
    accept-loop
;

Each connection runs in its own strand. The recursive accept-loop runs forever without growing the stack - TCO converts the tail call into a jump. No callbacks, no async/await, just sequential code that scales.

Why Strands?

Traditional threading has problems:

• OS threads are expensive (~1MB stack each)
• Context switching is slow
• Shared memory requires careful locking

Strands solve these:

• Lightweight (128KB coroutine stack per strand, fixed, configurable via SEQ_STACK_SIZE)
• Cooperative scheduling (fast context switch)
• Message passing via channels (no shared state)

Write code that reads sequentially, runs concurrently.

Understanding Type Errors

Seq’s type system tracks two orthogonal concepts:

A stack effect describes what a word does - its inputs and outputs. A stack type describes what is - the current stack contents.

Type errors occur when your stack type doesn’t satisfy a word’s input requirements:

i.divide: stack type mismatch. Expected (..a$0 Int Int), got (..rest Float Float): Type mismatch: cannot unify Int with Float

Here, i.divide has stack effect ( Int Int -- Int ). The compiler checks: “Does the current stack type have two Int values on top?” Your stack type (..rest Float Float) has two Float values instead - mismatch.

Reading the Error

The format (..name Type Type ...) represents a stack state:

So (..a$0 Int Int) means: “any stack with two Int values on top.”

Visual Breakdown

i.divide: stack type mismatch. Expected (..a$0 Int Int), got (..rest Float Float)
                                         │     │   │           │      │     │
                                         │     │   └── top     │      │     └── top
                                         │     └── 2nd         │      └── 2nd
                                         └── rest of stack     └── rest of stack

Translation:
  i.divide expects: ( ..a Int Int -- ..a Int )  ← two Ints in, one Int out
  You provided:   ( ..rest Float Float )      ← two Floats
  Problem:        Int ≠ Float

Row Variables Enable Polymorphism

The ..a notation (row variable) is what makes words like dup work on any stack depth:

: dup ( ..a T -- ..a T T )

This says: “Whatever is on the stack (..a), plus some value of type T on top, I’ll duplicate that T, leaving the rest untouched.”

Row variables let the type checker verify stack effects without knowing the full stack contents - only the parts each word actually touches.

Common Type Errors

Seq: where composition is not just a pattern, but the foundation.

Examples

Note: This file is auto-generated from README files in the examples/ directory. Run just gen-docs to regenerate, or edit the source README files.

Basics

Getting started with Seq - the simplest programs to verify your setup.

hello-world.seq

The canonical first program:

: main ( -- Int ) "Hello, World!" io.write-line 0 ;

cond.seq

Demonstrates the cond combinator for multi-way branching - a cleaner alternative to nested if/else.

Language Features

Core Seq language concepts demonstrated through focused examples.

Stack Effects (stack-effects.seq)

Stack effect declarations and how the type checker enforces them:

: square ( Int -- Int ) dup i.* ;

Quotations (quotations.seq)

Anonymous code blocks that can be passed around and called:

: apply-twice ( Int { Int -- Int } -- Int )
  dup rot swap call swap call ;

5 [ 2 i.* ] apply-twice  # Result: 20

Closures (closures.seq)

Quotations that capture values from their environment:

: make-adder ( Int -- { Int -- Int } )
  { i.+ } ;

10 make-adder  # Creates a closure that adds 10
5 swap call    # Result: 15

Control Flow (control-flow.seq)

Conditionals, pattern matching, and loops:

: fizzbuzz ( Int -- String )
  dup 15 i.modulo drop 0 i.= if drop "FizzBuzz"
  else dup 3 i.modulo drop 0 i.= if drop "Fizz"
  else dup 5 i.modulo drop 0 i.= if drop "Buzz"
  else int->string
  then then then ;

Recursion (recursion.seq)

Tail-recursive algorithms with guaranteed TCO:

: factorial-acc ( Int Int -- Int )
  over 0 i.<= if nip
  else swap dup rot i.* swap 1 i.- swap factorial-acc
  then ;

: factorial ( Int -- Int ) 1 factorial-acc ;

Strands (strands.seq)

Lightweight concurrent execution:

[ "Hello from strand!" io.write-line ] strand.spawn

Union Types (unions.seq)

Algebraic data types (sum types) with pattern matching:

union Option {
  Some { value: Int }
  None
}

: unwrap-or ( Option Int -- Int )
  swap match
    Some { >value } -> nip    # return the value
    None ->                   # return the default
  end
;

42 Make-Some 0 unwrap-or   # Result: 42
Make-None 99 unwrap-or     # Result: 99

Covers Option, Result, Message passing, and recursive tree structures.

Include Demo (main.seq, http_simple.seq)

Demonstrates the module include system for code organization.

Programming Paradigms

Seq is flexible enough to express multiple programming paradigms. These examples demonstrate different approaches to structuring programs.

Object-Oriented (oop/)

shapes.seq - OOP patterns using unions and pattern matching:

• Encapsulation: data bundled in union variants
• Polymorphism: pattern matching dispatches to correct implementation
• Factory functions as constructors
• Type checks via variant.tag (like instanceof)

union Shape {
  Circle { radius: Float }
  Rectangle { width: Float, height: Float }
}

: shape.area ( Shape -- Float )
  match
    Circle { >radius } -> dup f.* 3.14159 f.*
    Rectangle { >width >height } -> f.*
  end ;

Actor Model (actor/)

actor_counters.seq - CSP/Actor demonstration with hierarchical aggregation:

Company (aggregate)
  └── Region (aggregate)
        └── District (aggregate)
              └── Store (counter)

Features:

• Independent strands communicate via channels
• HTTP interface for queries and updates
• Request-response pattern with response channels

counter.seq - Simple generator pattern using weaves.

sensor-classifier.seq - Stream processing with structured data.

Functional (functional/)

lists.seq - Higher-order functions and list processing:

## Built-in higher-order functions
list-of 1 lv 2 lv 3 lv 4 lv 5 lv
  [ 2 i.* ] list.map       # (2 4 6 8 10)
  [ 2 mod 0 i.= ] list.filter  # keep evens
  0 [ i.+ ] list.fold      # sum

## Functional pipelines
list-of 1 lv 2 lv 3 lv 4 lv 5 lv 6 lv 7 lv 8 lv 9 lv 10 lv
  keep-odds      # filter to 1,3,5,7,9
  square-each    # map to 1,9,25,49,81
  sum            # fold to 165

Features:

• map: Transform each element with a quotation
• filter: Keep elements matching a predicate
• fold: Reduce list to single value with accumulator
• Composable operations for data pipelines

Logic (logic/)

Coming soon - Backtracking, unification patterns.

Dataflow (dataflow/)

Coming soon - Reactive and stream-based patterns.

Data Formats & Structures

Working with structured data in Seq.

JSON (json/)

json_tree.seq - Parse and traverse JSON:

include std:json

: main ( -- Int )
  "{\"name\": \"Alice\", \"age\": 30}" json.parse
  "name" json.get json.as-string io.write-line
  0 ;

YAML (yaml/)

YAML parsing with support for:

• Multiline strings
• Nested structures
• Anchors and aliases

SON (son/)

serialize.seq - Seq Object Notation, Seq’s native serialization format optimized for stack-based data.

Zipper (zipper/)

zipper-demo.seq - Functional list navigation with O(1) cursor movement:

include std:zipper

{ 1 2 3 4 5 } list->zipper
zipper.right zipper.right  # Move to element 3
100 zipper.set             # Replace with 100
zipper.to-list             # { 1 2 100 4 5 }

Encoding (encoding.seq)

Base64, hex, and other encoding/decoding operations.

JSON Examples

Practical examples demonstrating JSON parsing and serialization in Seq.

json_tree.seq - JSON Tree Viewer

An interactive tool that reads JSON from files, command-line, or stdin, parses it, and displays the structure.

Usage

### Build
cargo build --release
./target/release/seqc --output json_tree examples/json/json_tree.seq

### Read from a JSON file (preferred)
./json_tree config.json
./json_tree data/users.json

### Or with command-line JSON string
./json_tree '42'
./json_tree 'true'
./json_tree '"hello world"'
./json_tree '[42]'

### Or with piped input
echo '42' | ./json_tree

### Or interactive (type JSON, press Enter)
./json_tree

Example Output

$ ./json_tree '[42]'
=== JSON Tree Viewer ===

Input: [42]

Type: 4
Value:
  [42]

Type codes: 0=null, 1=bool, 2=number, 3=string, 4=array, 5=object

What This Example Reveals We Need

Building this practical example highlighted several missing features that would make Seq more useful for real-world JSON processing:

Implemented

1. Command-line arguments (arg-count, arg) ✓

   • arg-count returns number of arguments (including program name)
   • arg takes an index and returns the argument string
   • Example: ./json_tree '[42]' now works!

2. File I/O (file-slurp, file-exists?) ✓

   • file-slurp reads entire file contents as a string
   • file-exists? checks if a file exists (returns 1 or 0)
   • Example: ./json_tree config.json now works!

3. Multi-element arrays (up to 2 elements) ✓

   • [1], [1, 2], ["a", "b"], [42, "mixed"]
   • Strings, numbers, booleans all work inside arrays

4. Strings at any position ✓

   • Strings now parse correctly whether top-level or inside arrays
   • "hello", ["hello"], ["a", "b"] all work

5. Multi-element arrays ✓

   • Arrays with any number of elements: [1, 2, 3, ...]
   • Nested arrays: [[1, 2], [3, 4]]
   • Mixed content: [1, "hello", true, null]

6. Multi-pair objects ✓

   • Objects with any number of key-value pairs
   • Nested objects: {"person": {"name": "John", "age": 30}}
   • Complex structures: [{"name": "John"}, {"name": "Jane"}]

7. Functional collection builders ✓

   • array-with: ( arr val -- arr' ) - append to array
   • obj-with: ( obj key val -- obj' ) - add key-value pair
   • variant-append: low-level primitive for building variants

High Priority

1. Write without newline (write vs write_line)
   • Would allow proper indentation output
   • Currently can only output complete lines

Medium Priority

2. Pattern matching / case statement
   • Would simplify tag-based dispatch
   • Currently requires nested if/else chains

Nice to Have

5. String escape sequences (\", \\, \n)
6. Pretty-print with indentation levels
7. JSON path queries ($.foo.bar)

Current JSON Support

Works:

• Primitives: null, true, false
• Numbers: 42, -3.14, 1e10
• Strings: "hello", "hello world" (no escapes)
• Arrays: [], [1], [1, 2], [1, 2, 3], nested arrays, any length
• Objects: {}, {"a": 1}, {"a": 1, "b": 2}, nested objects, any number of pairs
• Complex nested structures: [{"name": "John", "age": 30}, {"name": "Jane"}]

Serialization limits (parsing works for any size):

• Arrays: up to 3 elements display fully, 4+ show as [...]
• Objects: up to 2 pairs display fully, 3+ show as {...}

Limitations:

• String escapes: "say \"hi\"" - not supported

Technical Notes

Why Serialization Has Size Limits

The serializer (json-serialize-array, json-serialize-object) uses nested if/else chains to handle different sizes (0, 1, 2, 3 elements). This is because Seq currently lacks:

1. Loops - No for i in 0..count construct
2. Tail-call optimization - Recursion would blow the stack for large collections
3. Variant fold/map - No way to iterate over variant fields from Seq

Possible solutions:

• Add a variant-fold runtime primitive: ( variant init quot -- result )
• Add counted loops to the language
• Implement TCO for recursive serialization

Why Parsing Has No Size Limits

Parsing uses recursive descent with the functional builders (array-with, obj-with). Each recursive call builds up the collection incrementally. The stack usage is proportional to nesting depth, not collection size, so [1,2,3,...,1000] works fine but deeply nested structures could overflow.

YAML Examples

Examples demonstrating the YAML parsing library implemented in Seq.

Overview

The YAML library (std:yaml) is written entirely in Seq, using only the existing language primitives. This validates that the builtin/stdlib balance allows building complex parsers without language changes.

Primitives Used

The YAML parser uses these existing primitives:

• String operations: string-find, string-substring, string-trim, string-empty, string-length, string-char-at, string-concat, string->float
• Character conversion: char->string
• Variant operations: make-variant-0, make-variant-1, variant-tag, variant-field-at, variant-field-count, variant-append
• Standard stack operations: dup, drop, swap, over, rot
• Arithmetic and comparison: add, subtract, <, >, =, <>
• Control flow: if/else/then

No new primitives were required.

Examples

yaml_test.seq

Basic tests for single-line YAML parsing:

• Strings: name: John
• Numbers: age: 42, price: 19.99
• Booleans: active: true, enabled: false
• Null: data: null, empty: ~

yaml_multiline.seq

Tests for multi-line YAML documents:

• Multiple key-value pairs
• Blank lines (ignored)
• Comments (lines starting with #)

Running

cargo run --release -- examples/yaml/yaml_test.seq -o /tmp/yaml_test
/tmp/yaml_test

cargo run --release -- examples/yaml/yaml_multiline.seq -o /tmp/yaml_multi
/tmp/yaml_multi

Supported YAML Features

• Multi-line documents with multiple key-value pairs
• String values (unquoted)
• Integer and floating-point numbers
• Booleans (true/false)
• Null values (null or ~)
• Comments (# to end of line)
• Blank lines

Not Yet Supported

• Nested objects (indentation-based nesting)
• Arrays/lists (- item syntax)
• Multi-line strings (| and > block scalars)
• Quoted strings with escapes
• Anchors and aliases

Input/Output

File I/O, terminal, OS, text processing, compression. The non-network side of I/O.

For networking examples (TCP, UDP, TLS, DNS, HTTP) see ../net/.

Terminal (terminal/)

terminal-demo.seq - Terminal colors, cursor control, and formatting using ANSI escape sequences.

Operating System (os/)

os-demo.seq - Environment variables, paths, and system information.

Text Processing (text/)

log-parser.seq - Parsing structured log files with string operations.

regex-demo.seq - Regular expression matching and extraction.

Compression (compress-demo.seq)

Zstd compression and decompression for efficient data storage.

Networking

Five layers, bottom to top: DNS → TCP → UDP → TLS → HTTP. Each subfolder has runnable example(s) using the corresponding net.* builtins.

The stack is may-aware end to end: every IO step yields the cooperative carrier instead of blocking it. Hostnames resolve through a dedicated worker pool so getaddrinfo runs off the carrier. See docs/STDLIB_REFERENCE.md for the full word reference, or docs/design/done/NONBLOCKING_NETWORKING.md for the design rationale.

Examples

dns/resolve.seq — net.dns.resolve

Resolves a hostname and prints each IP returned. Demonstrates the worker-pool-offload path; useful as a one-liner for “what does this hostname actually resolve to from inside Seq.”

seqc build dns/resolve.seq -o /tmp/dns-resolve
/tmp/dns-resolve

tcp/client.seq — net.tcp.connect

Minimal TCP client: connect to example.com:80, send an HTTP/1.0 request, read the response, close. Plain TCP — no framing helpers — to show what net.tcp.* looks like on its own.

seqc build tcp/client.seq -o /tmp/tcp-client
/tmp/tcp-client

tcp/server.seq — plain TCP echo server

Not all networking is HTTP. Accepts a TCP connection, echoes whatever the client sent back, closes. Each connection runs in its own strand (green thread) so the server handles concurrent clients cooperatively.

seqc build tcp/server.seq -o /tmp/tcp-server
/tmp/tcp-server &
echo hello | nc localhost 9000

tcp/http-routing.seq — HTTP server on top of net.tcp.*

The companion to tcp/server.seq: same accept-loop shape, with HTTP/1.1 request parsing and a cond-driven router on top. Doubles as a tutorial on concatenative programming (the source is heavily commented). Lives under tcp/ because net.http.* is client-only — the server is hand-rolled over net.tcp.read / net.tcp.write.

seqc build tcp/http-routing.seq -o /tmp/http-routing
/tmp/http-routing &
curl http://localhost:8080/
curl http://localhost:8080/health
curl http://localhost:8080/echo
curl http://localhost:8080/invalid   # 404

udp/echo.seq — net.udp.bind + net.udp.send-to + net.udp.receive-from

Single-program UDP loopback: bind two sockets, send a datagram from one to the other, receive it, print. Mirrors the round-trip pattern the integration test uses.

seqc build udp/echo.seq -o /tmp/udp-echo
/tmp/udp-echo

tls/client.seq — net.tls.client

The TCP client above with one extra step: after net.tcp.connect returns the Socket, net.tls.client upgrades it in place to a TLS-wrapped Socket. Subsequent net.tcp.read / net.tcp.write calls dispatch through rustls transparently — the rest of the code looks exactly like the plain-TCP version.

seqc build tls/client.seq -o /tmp/tls-client
/tmp/tls-client

http/client.seq — net.http.get / .post / .put / .delete

High-level HTTP/1.1 client: hand net.http.get a URL, get a response Map back (status, body, ok, error). The client handles DNS resolution, SSRF validation against the resolved IPs, connection pooling keyed on (scheme, host, port), TLS for https://, and HTTP/1.1 framing — all the layers below are still there, just composed into one builtin. Exercises GET, POST, PUT, DELETE against httpbin.org.

seqc build http/client.seq -o /tmp/http-client
/tmp/http-client

Reading order

For a layered tour, read top-to-bottom: dns/resolve.seq → tcp/client.seq → tcp/server.seq → tls/client.seq → http/client.seq. The HTTP-routing server (tcp/http-routing.seq) is the “everything on top of TCP” deep dive once the rest clicks.

What’s not here yet

• mTLS, ALPN selection, peer-cert inspection (planned follow-ups — see issue #483 for the test anchors).
• Per-request timeouts (planned — see issue #484).
• A header-bag API for custom HTTP request headers.

Complete Projects

Larger applications demonstrating Seq’s capabilities.

Lisp Interpreter (lisp/)

A complete Lisp interpreter in Seq:

Supported features:

• Numbers and symbols
• Arithmetic: +, -, *, /
• let bindings
• if conditionals
• lambda with closures

This project demonstrates:

• Union types (ADTs) for the AST
• Pattern matching for dispatch
• Recursive descent parsing
• Environment passing for lexical scope

Hacker’s Delight (hackers-delight/)

Bit manipulation algorithms from the book Hacker’s Delight:

Demonstrates Seq’s bitwise operations: band, bor, bxor, shl, shr, popcount, clz, ctz.

Shamir’s Secret Sharing (sss.seq)

A tutorial implementation of Shamir’s Secret Sharing over GF(256), the same finite field used by AES. A secret is split into N shares such that any K can reconstruct it, but K-1 shares reveal nothing.

Demonstrates:

• GF(256) finite field arithmetic — addition (XOR), peasant multiplication, Fermat inverse
• Polynomial evaluation via Horner’s method
• Lagrange interpolation to reconstruct secrets from share subsets
• Packed accumulators — encoding two byte values in one Int for list.fold
• Deep stack management — pick/roll patterns for 4+ item stacks
• Cryptographic randomness — crypto.random-int for polynomial coefficients

Cryptography (crypto.seq)

Cryptographic operations including hashing and encoding.

Shopping Cart (shopping-cart/)

A domain modeling example showing how to structure a typical business application with Seq.

Hacker’s Delight Examples

Bit manipulation puzzles inspired by the classic techniques in low-level programming.

Files

Running

seqc examples/hackers-delight/01-rightmost-bits.seq -o /tmp/demo && /tmp/demo

Bitwise Operations Used

These examples use Seq’s bitwise operations:

• band - bitwise AND
• bor - bitwise OR
• bxor - bitwise XOR
• bnot - bitwise NOT
• shl - shift left
• shr - logical shift right
• popcount - count 1-bits
• clz - count leading zeros
• ctz - count trailing zeros
• int-bits - bit width (63 — Seq Int is signed 63-bit)

Numeric Literals

Seq supports hex and binary literals for bit manipulation:

0xFF        # hex: 255
0b10101010  # binary: 170

Seq → OSC → Csound (live-coding POC)

This directory is the Phase C POC from docs/design/LIVE_CODING_CSOUND_POC.md: prove that Seq can drive an external audio engine (Csound) over OSC well enough to support live-coding music.

What’s here

Audible run

The encoder/loopback tests run in CI (just ci). The audible parts below need a working Csound install on your machine.

1. Install Csound

macOS (Homebrew):

brew install csound

Linux (Debian/Ubuntu):

sudo apt-get install csound

Verify:

csound --version

2. Start the listener

In one terminal, from the repo root:

csound -odac examples/projects/live-coding-csound/live.csd

-odac writes audio to your default output device. You should see Csound print its banner, list the instruments, and sit waiting (last line will say something like SECTION 1: followed by no further output). Leave this terminal running.

3. Send one kick (tone.seq)

In a second terminal, build and run the one-shot driver:

just build
target/examples/projects-live-coding-csound-tone

You should hear a single short percussive tone at 220 Hz. The Seq process exits immediately; Csound stays up so you can run again.

4. Run the metronome (live.seq)

target/examples/projects-live-coding-csound-live

You should hear 8 evenly-spaced kicks over roughly 4 seconds (120 BPM).

5. Live-coding loop

Edit live.seq (e.g. change bpm-ms from 500 to 250 for 240 BPM, or beats from 8 to 16), then run just build and re-execute the binary. Csound keeps running between Seq runs, so the iteration cycle is just edit → build → re-run.

To stop everything: Ctrl+C in the Csound terminal.

Troubleshooting

Nothing audible after tone/live. Check the Csound terminal: when an OSC message lands, Csound prints something like new alloc for instr 2: and ihold: lines. If those are absent, the message isn’t reaching Csound. Verify the port matches (Csound listens on 7770; Seq sends to 7770).

csound: command not found. Install per step 1 above.

Address already in use from Csound. Another process holds port 7770. lsof -i :7770 to find it; kill the holder or change the port in both live.csd and the 7770 literal in tone.seq / live.seq.

Audio cuts out / glitches. Csound’s default audio backend can be finicky. Try csound -odac0 live.csd to force the system default device, or pass -+rtaudio=... to pick a specific backend (CoreAudio on macOS, ALSA/JACK on Linux).

How this fits the design doc

• Checkpoint 1 (UDP loopback) — covered by test_osc_loopback.seq, runs in CI.
• Checkpoint 2 (OSC fixture test) — covered by test_osc.seq, runs in CI.
• Checkpoint 3 (Csound responds, one tone) — tone.seq + this README. Manual verification.
• Checkpoint 4 (a bar of music) — live.seq + this README. Manual verification.
• Checkpoint 5 (POC writeup decides spinout question) — once you’ve run the metronome a few times and exercised the edit-build-rerun loop, the design doc gets a final block recording what worked, what surfaced as a Seq language gap, and whether the whole thing is worth spinning into its own repo.

Foreign Function Interface

Calling native C libraries from Seq.

SQLite (sqlite/)

sqlite-demo.seq - Database access through FFI:

include ffi:sqlite

: main ( -- Int )
  "test.db" sqlite.open
  "CREATE TABLE users (id INTEGER, name TEXT)" sqlite.exec
  "INSERT INTO users VALUES (1, 'Alice')" sqlite.exec
  "SELECT * FROM users" sqlite.query
  sqlite.close
  0 ;

Requires sqlite.toml manifest defining the FFI bindings.

Libedit (libedit-demo.seq)

Readline-style input using the libedit library for interactive command-line applications.

Creating FFI Bindings

1. Create a TOML manifest defining the C functions
2. Use include ffi:name to load the bindings
3. Call functions with Seq-style names (e.g., sqlite.open)

See the FFI Guide for complete documentation.

SQLite FFI Example

This example demonstrates using SQLite via FFI, including the by_ref pass mode for out parameters (used by sqlite3_open to return the database handle).

Building

seqc --ffi-manifest examples/ffi/sqlite/sqlite.toml \
     examples/ffi/sqlite/sqlite-demo.seq \
     -o sqlite-demo
./sqlite-demo

Dependencies

• macOS: SQLite is pre-installed
• Ubuntu/Debian: apt install libsqlite3-dev
• Fedora: dnf install sqlite-devel

FFI Features Demonstrated

by_ref Out Parameters

SQLite’s sqlite3_open returns the database handle via an out parameter:

int sqlite3_open(const char *filename, sqlite3 **ppDb);

In the FFI manifest, this is declared as:

[[library.function]]
c_name = "sqlite3_open"
seq_name = "db-open"
stack_effect = "( String -- Int Int )"
args = [
  { type = "string", pass = "c_string" },
  { type = "ptr", pass = "by_ref" }
]
[library.function.return]
type = "int"

The by_ref argument doesn’t come from the Seq stack - instead:

1. The compiler allocates local storage
2. Passes a pointer to that storage to the C function
3. After the call, reads the value and pushes it onto the stack

Result: db-open has stack effect ( String -- Int Int ) where the first Int is the database handle (from the out param) and the second is the return code.

Important: Ownership Semantics

The by_ref pointer value pushed onto the stack is an opaque handle owned by the C library (SQLite in this case). You must:

• Only pass it to functions from the same library (e.g., db-exec, db-close)
• Never attempt to free it manually
• Always close/release it using the library’s cleanup function (db-close)
• Not store it beyond its valid lifetime

The compiler treats these as integers for simplicity, but they are NOT arbitrary integers - they are pointers that must be used according to the C library’s API.

Fixed Value Arguments

For sqlite3_exec, we pass NULL for unused callback parameters:

args = [
  { type = "ptr", pass = "ptr" },
  { type = "string", pass = "c_string" },
  { type = "ptr", value = "null" },  # callback
  { type = "ptr", value = "null" },  # callback arg
  { type = "ptr", value = "null" }   # error msg
]

Arguments with value don’t come from the stack - they’re compiled as constants.

See Also

• Language Guide - Core language concepts
• Weaves Guide - Generators and coroutines
• Testing Guide - Writing and running tests
• seqlings - Interactive exercises

Testing Guide

Seq includes a built-in test framework for writing and running tests. Tests are discovered automatically and run with seqc test.

Quick Start

Create a file named test-math.seq:

: test-addition ( -- )
  "Addition" test.init
  1 2 i.+ 3 test.assert-eq
  test.finish
;

: test-multiplication ( -- )
  "Multiplication" test.init
  3 4 i.* 12 test.assert-eq
  test.finish
;

Run tests:

seqc test

Output:

test-math.seq
  test-addition ... ok
  test-multiplication ... ok

2 tests passed, 0 failed

Test Discovery

The test runner uses two naming conventions plus a signature check:

1. Test files: Files named test-*.seq are discovered automatically.
2. Test functions: Words named test-* are run as tests only when their declared stack effect is exactly ( -- ). A test-* word with a different signature (e.g. a test-flag ( Int Int -- Bool ) helper) is skipped, not promoted to an entry point.

myproject/
  src/
    parser.seq
    eval.seq
  tests/
    test-parser.seq    # Discovered
    test-eval.seq      # Discovered
    helpers.seq        # NOT discovered (no test- prefix)

Run tests in a directory:

seqc test tests/           # Run all test-*.seq files in tests/
seqc test test-parser.seq  # Run specific file
seqc test .                # Run all tests in current directory (recursive)

If you pass an explicit file path that doesn’t match test-*.seq, the runner errors instead of silently producing zero results:

$ seqc test tests/parser.seq
Test files must be named `test-*.seq`. Got: `tests/parser.seq`

Why test- predicates are safe

Inside a test-*.seq file, you can still define helpers whose names start with test- — for example, predicate-style words ending in ? or domain probes that take arguments. The signature filter excludes any test-* word that doesn’t match ( -- ), so it never gets called with an empty stack, and the runner prints a one-line note explaining why it was skipped:

test-flag ... skipped — name starts with `test-` but stack effect is
( Int Int -- Bool ), not ( -- ). Rename if it's a helper; fix the
signature if it's a test.

The note distinguishes “you have a helper that happens to start with test-” from “your test silently disappeared” — if you wrote what you thought was a test and see this skip note, fix the signature.

Test Framework Builtins

For test.assert-eq and test.assert-eq-str, push the actual (computed) value first and the expected (literal) value on top. On failure the runner prints expected <top>, got <below>.

Writing Tests

Basic Structure

Every test function should:

1. Call test.init with a descriptive name
2. Run assertions
3. Call test.finish

: test-string-operations ( -- )
  "String operations" test.init

  # Test concatenation
  "hello" " " string.concat "world" string.concat
  "hello world" test.assert-eq-str

  # Test length
  "abc" string.length 3 test.assert-eq

  # Test empty check
  "" string.empty? test.assert
  "x" string.empty? test.assert-not

  test.finish
;

Testing with Setup

For tests needing setup, extract helpers:

: make-test-list ( -- List )
  list.make
  1 list.push
  2 list.push
  3 list.push
;

: test-list-length ( -- )
  "List length" test.init
  make-test-list list.length 3 test.assert-eq
  test.finish
;

: test-list-sum ( -- )
  "List sum" test.init
  make-test-list 0 [ i.+ ] list.fold
  6 test.assert-eq
  test.finish
;

Testing Error Cases

Use test.fail for cases that shouldn’t be reached:

: test-option-handling ( -- )
  "Option handling" test.init

  Make-None match
    None -> "none handled" drop
    Some { >value } -> "Should not reach Some" test.fail
  end

  42 Make-Some match
    None -> "Should not reach None" test.fail
    Some { >value } -> value 42 test.assert-eq
  end

  test.finish
;

Testing Stack Effects

Test that operations produce expected stack results:

: test-stack-ops ( -- )
  "Stack operations" test.init

  # Test dup
  5 dup
  5 test.assert-eq  # top should be 5
  5 test.assert-eq  # second should also be 5

  # Test swap
  1 2 swap
  1 test.assert-eq  # top should be 1
  2 test.assert-eq  # second should be 2

  test.finish
;

Running Tests

Basic Usage

seqc test                    # Run all test-*.seq in current directory
seqc test tests/             # Run all tests in tests/ directory
seqc test test-parser.seq    # Run specific test file

Filtering Tests

Run only tests matching a pattern:

seqc test -f parse           # Run tests with "parse" in the name
seqc test -f test-add        # Run tests starting with "test-add"

Verbose Output

See timing for each test:

seqc test -v

Output:

test-math.seq
  test-addition ... ok (2ms)
  test-multiplication ... ok (1ms)
  test-division ... ok (1ms)

3 tests passed, 0 failed (4ms total)

Failure Output

When an assertion fails, the runner reports the source line, the expected value, and the actual value on the stack:

tests/test-math.seq::test-addition
  test-addition ... FAILED
    at line 6: expected 8, got 13

Multiple failures within a single test each get their own line. Tests that fire many assertions (e.g. loop-like comparisons over a list) cap the output at the first five failures and append a +N more failures footer so the real signal isn’t buried:

tests/test-math.seq::test-many
  test-many ... FAILED
    at line 3: expected 1, got 99
    at line 4: expected 2, got 99
    at line 5: expected 3, got 99
    at line 6: expected 4, got 99
    at line 7: expected 5, got 99
    +2 more failures

Standalone Test Files

If your test file has a main function, it runs as a standalone program instead of using the test runner:

# test-manual.seq - has main, runs standalone
: test-helper ( -- ) ... ;

: main ( -- )
  # Custom test harness
  "Running manual tests" io.write-line
  test-helper
  "All tests passed!" io.write-line
;

This is useful for tests requiring custom setup or integration tests.

Best Practices

1. One Assertion Per Concept

Group related assertions, but keep tests focused:

# Good - focused test
: test-empty-list-length ( -- )
  "Empty list length" test.init
  list.make list.length 0 test.assert-eq
  test.finish
;

# Good - related assertions grouped
: test-list-push ( -- )
  "List push" test.init
  list.make
  1 list.push list.length 1 test.assert-eq
  2 list.push list.length 2 test.assert-eq
  test.finish
;

2. Descriptive Test Names

Use names that describe what’s being tested:

: test-parser-handles-empty-input ( -- ) ... ;
: test-parser-rejects-invalid-syntax ( -- ) ... ;
: test-eval-arithmetic-precedence ( -- ) ... ;

3. Clean Up State

Tests run sequentially. Clean up any global effects:

: test-with-cleanup ( -- )
  "Test with cleanup" test.init
  # ... test code ...
  test.finish
  # Clean up any channels, files, etc.
;

4. Test Edge Cases

Cover boundaries and special cases:

: test-division-edge-cases ( -- )
  "Division edge cases" test.init
  0 5 i./ drop 0 test.assert-eq        # 0 / n = 0
  5 1 i./ drop 5 test.assert-eq        # n / 1 = n
  0 7 i.- 3 i./ drop 0 2 i.- test.assert-eq  # negative division
  test.finish
;

Example: Testing a Parser

include "parser"

: test-parse-number ( -- )
  "Parse number" test.init
  "42" parse match
    ParseOk { >value } -> value 42 test.assert-eq
    ParseErr { >msg } -> msg test.fail
  end
  test.finish
;

: test-parse-invalid ( -- )
  "Parse invalid input" test.init
  "not-a-number" parse match
    ParseOk { >value } -> drop "Should have failed" test.fail
    ParseErr { >msg } -> drop  # Expected error
  end
  test.finish
;

: test-parse-empty ( -- )
  "Parse empty string" test.init
  "" parse match
    ParseOk { >value } -> drop "Should have failed" test.fail
    ParseErr { >msg } -> drop  # Expected error
  end
  test.finish
;

See Also

• examples/ - Many examples include tests
• Standard Library - Full builtin reference

Seq Standard Library Reference

This document covers:

• Built-in Operations - primitives implemented in the runtime
• Standard Library Modules - Seq code included via include std:<module>

Table of Contents

Built-in Operations

• I/O Operations
• Command-line Arguments
• File Operations
• Type Conversions
• Integer Arithmetic
• Integer Comparison
• Boolean Operations
• Bitwise Operations
• Stack Operations
• Control Flow
• Concurrency
• Channel Operations
• Networking — net.tcp.*
• Networking — net.udp.*
• Networking — net.dns.*
• Networking — net.tls.*
• Networking — Socket type
• OS Operations
• Terminal Operations
• String Operations
• Encoding Operations
• Crypto Operations
• Networking — net.http.* (HTTP client)
• Regular Expressions
• Compression
• Variant Operations
• List Operations
• Map Operations
• Float Arithmetic
• Float Comparison
• Float Math
• Test Framework
• Time Operations
• Serialization
• Stack Introspection

Standard Library Modules

• std:json
• std:yaml
• std:http
• std:list
• std:map
• std:imath
• std:fmath
• std:zipper
• std:signal
• std:son
• std:stack-utils

I/O Operations

Command-line Arguments

File Operations

Directory Operations

Type Conversions

Integer Arithmetic

Division and Modulo Behavior

Division and modulo operations return a result and a success flag:

• Success (true): Operation completed normally, result is valid
• Failure (false): Division by zero, result is 0

Overflow handling: INT_MIN / -1 uses wrapping semantics and returns INT_MIN with success=true. This matches Forth/Factor behavior and avoids undefined behavior.

10 3 i./     # ( -- 3 true )   Normal division
10 0 i./     # ( -- 0 false )  Division by zero
-9223372036854775808 -1 i./  # ( -- -9223372036854775808 true )  Wrapping

Integer Comparison

Boolean Operations

Bitwise Operations

Stack Operations

Control Flow

Concurrency

Channel Operations

Networking — net.tcp.*

All TCP operations return a Bool success flag for error handling. The fd slot is typed as Socket (a phantom over Int) — net.tcp.write will not accept an arbitrary integer.

Note on net.tcp.local-port and Socket id aliasing. Listeners and connected streams live in separate registries that each start their id sequence at 0, so the same Socket integer can refer to different resources depending on which registry holds it. Dispatch for local-port (and for close) is streams-first, then listeners. The practical implication: if you intend to read a listener’s local port, call net.tcp.local-port on it before allocating any connected streams (or stash the result eagerly), otherwise an id that aliases between the two registries will return the stream’s port. Tracked as a broader follow-up; in the meantime treat Socket ids as resource-local, not globally unique.

net.tcp.connect resolves the hostname through net.dns.resolve — the lookup runs on the DNS worker pool, not the may carrier, and tries each returned address in order until one connects (or all fail). IP literals work as hostnames (they round-trip through getaddrinfo without touching DNS). Bool is false on resolution failure, every-address-failed, invalid port (must be 1..65535), or socket-registry exhaustion.

Connect timeout. Each connect attempt is bounded by a default 10s deadline. A peer that silently drops SYNs surfaces as a connect failure in seconds, not the kernel’s full SYN timeout (~60–130s on Linux). Override per-process with SEQ_TCP_CONNECT_TIMEOUT_MS (read once on first use; setting 0 falls back to the default). The bound applies per address — a multi-IP fallback that walks dead addresses sees N × timeout total wall time before giving up.

Known limitation — no happy-eyeballs. Addresses are tried in resolver order. If AAAA (IPv6) points somewhere unreachable on a misconfigured network, the connect-timeout fires per address before falling back to A (IPv4). RFC 8305 happy-eyeballs would parallelise this; it’s a planned follow-up.

"example.com" 443 net.tcp.connect
[ # ( socket )
  "GET / HTTP/1.0\r\nHost: example.com\r\n\r\n" over net.tcp.write drop
  dup net.tcp.read
  [ io.write-line ]
  [ drop "read failed" io.write-line ]
  if
  net.tcp.close drop
]
[ drop "connect failed" io.write-line ]
if

Networking — net.udp.*

Datagram-oriented; sockets are Socket handles. Every word ends with a success Bool on top so callers can [ ... ] [ ... ] if.

net.udp.send-to host resolution. Hostnames in the host argument are resolved through net.dns.resolve — the may-aware DNS worker pool — so the carrier thread does not park on a blocking getaddrinfo. IP literals work without DNS round-trip. If resolution returns multiple addresses (e.g. localhost → ::1, 127.0.0.1) the addresses are tried in order; the first send_to that doesn’t error wins, which transparently handles the case of a v4-only socket reached through a name that resolves v6-first.

Note: for UDP, send_to returning OK means the kernel accepted the datagram for the chosen address family — it does not confirm peer receipt. The multi-address walk therefore catches local-side errors (address-family mismatch, route-not-found) but cannot detect an unreachable peer past the first successful queue.

Networking — net.dns.*

Hostname resolution offloaded to a dedicated OS-thread pool so may carriers never park on getaddrinfo. A small TTL cache (60s, max 256 entries) collapses fanout to the same host. Inherits all platform-correct resolution behaviour (/etc/hosts, systemd-resolved, VPN/corp DNS, mDNS) from libc.

The list contains IP-string representations ("127.0.0.1", "::1", …). IP literals fast-path through getaddrinfo without touching DNS.

Worker count is configurable via SEQ_DNS_WORKERS (default 8, max 64). SEQ_DNS_WORKERS=0 is treated as unset and falls back to the default — disabling the pool makes no architectural sense since the syscall has to run somewhere off the may carrier.

Fanout collapsing. Both sequential and concurrent fanout collapse to a single getaddrinfo. The TTL cache catches the sequential case. An in-flight map keyed by hostname catches the concurrent case: when N strands race to resolve the same uncached host, the first to arrive enqueues exactly one worker job and the others attach to the in-flight entry. When the worker returns it writes the cache and fans the result out to every attached strand.

IP-literal fast path. Callers that go through net.dns.resolve indirectly (via net.tcp.connect, net.udp.send-to, or the HTTP client’s SSRF validator) bypass the worker pool entirely when the host string is an IP literal — dns::resolve_to_ips parses the literal and returns it directly. The pool round-trip is reserved for actual DNS work.

"api.example.com" net.dns.resolve
[ "first IP: " io.write list.first
  [ io.write-line ] [ drop "no addresses" io.write-line ] if ]
[ "resolution failed" io.write-line ]
if

Networking — net.tls.*

TLS client upgrade for an already-connected Socket. The handshake runs eagerly inside the builtin (via rustls::ClientConnection::complete_io over the underlying may-aware TCP stream) so transport errors, bad certificates, hostname mismatches, and any other TLS-layer failure surface as (0, false) — matching every other fallible networking word. After a successful upgrade, the existing net.tcp.read / net.tcp.write / net.tcp.close operate on the returned Socket transparently — the runtime dispatches reads and writes through rustls. Trust roots come from webpki-roots.

Handshake timeout. Each individual read/write inside the rustls handshake is bounded by a default 10s deadline. A peer that accepts the TCP connection but goes silent mid-handshake surfaces as a handshake failure within that bound, rather than parking the strand indefinitely. Override with SEQ_TLS_HANDSHAKE_TIMEOUT_MS. (The per-IO budget applies to each round of the handshake, not the entire exchange — a slow but progressing handshake completes; a stalled one fails.)

Known limitations (v1):

• net.tcp.close on a TLS socket is a hard close. The underlying TCP stream is dropped without first sending the TLS close_notify alert (RFC 5246 expects clients to send it). Modern servers tolerate truncation; some older stacks log it as a truncation-attack indicator. A graceful-shutdown variant is a planned follow-up.
• IP-literal hostnames syntactically work but almost always fail validation. ServerName::try_from parses "1.2.3.4" cleanly, but cert validation against an IP requires the peer cert to carry that IP in a SubjectAltName entry — vanishingly rare for public-internet certs. Use a DNS name unless you control the peer cert.
• No client-certificate authentication (mTLS). A with_no_client_auth() config is used unconditionally. mTLS is a planned follow-up.
• No caller-side ALPN selection. Whatever rustls defaults negotiate (typically h2 / http/1.1 if the peer offers them) is what you get; there’s no way to ask for or reject a specific protocol.
• No peer-certificate or cipher inspection from Seq. Once the handshake succeeds, only the upgraded Socket is exposed — the negotiated suite, peer cert chain, SNI accepted, etc., are not surfaced.
• No session resumption knobs. rustls’s default in-process session cache applies; there’s no Seq-level control.

"example.com" 443 net.tcp.connect
[ # ( socket )
  "example.com" net.tls.client
  [ # ( socket )
    "GET / HTTP/1.0\r\nHost: example.com\r\n\r\n" over net.tcp.write drop
    dup net.tcp.read
    [ io.write-line ]
    [ drop "read failed" io.write-line ]
    if
    net.tcp.close drop
  ]
  [ drop "TLS handshake failed" io.write-line ]
  if
]
[ drop "connect failed" io.write-line ]
if

Networking — Socket type

Socket is a compile-time-only nominal wrapper over the Int file descriptor; the runtime representation stays Value::Int(fd). This means the type checker rejects 42 net.tcp.write. Two escape hatches exist for FFI / debugging:

OS Operations

Terminal Operations

String Operations

Encoding Operations

Crypto Operations

Networking — net.http.* (HTTP client)

The HTTP client lives under net.http.*. The std:http stdlib module provides server-side response/parsing helpers (http-ok, http-request-path, …) and is unrelated.

The client is hand-rolled HTTP/1.1 over the may-aware TCP and TLS primitives (see net.tcp.connect, net.tls.client). Every IO step yields the strand cooperatively; the request never parks the carrier thread. Hostname resolution and SSRF validation run through the net.dns.* worker pool, so there is exactly one getaddrinfo per request and it runs off the may carrier.

Response Map shape:

• "status" (Int): HTTP status code, or 0 on connection-level error.
• "body" (String): response body as raw bytes (byte-clean — binary downloads round-trip intact; decode as text yourself if you expected text).
• "ok" (Bool): true iff status is in 200..300.
• "error" (String): error message; present only on failure.

Connection pool. Keep-alive connections are pooled by (scheme, host, port) between requests. A second net.http.get against the same origin skips the TCP and TLS handshakes when an idle entry is available. Defaults:

• 8 idle connections per (scheme, host, port)
• 30s idle timeout
• 256 idle connections globally
• MRU checkout (freshest pooled connection used first)
• Non-blocking half-closed peek on reuse: if the peer FIN’d the socket while it sat idle, the entry is dropped and a fresh connection is dialled.

SSRF protection. Requests are blocked when the URL’s host resolves to a loopback (127.0.0.0/8, ::1), private (10/8, 172.16/12, 192.168/16), link-local (169.254/16, including cloud metadata endpoints), or unique-local (fc00::/7) IP. Schemes outside http/https are rejected. The check runs against the addresses the DNS layer already returned — no second resolution on the carrier.

v1 limitations:

• No redirect following. A 3xx response is returned to the caller as-is, with Location available in the body or via your own header parser.
• No automatic decompression. The client sends Accept-Encoding: identity. If you want gzip transfer, set up your own request and decompress with compress.gunzip.
• Per-IO request/response timeout (default 30s). Each individual read/write inside the wire layer (request send, response header read, every chunk read for chunked transfers, every read for EOF-framed bodies) is bounded by this deadline. A peer that goes silent mid-response — no bytes for timeout — surfaces as a wire error within the bound. Override with SEQ_HTTP_REQUEST_TIMEOUT_MS. The deadline is per-IO, not total: a peer that drips one byte every timeout − ε keeps each read under budget and so isn’t caught by this bound — practically, the residual exposure is capped at MAX_BODY_SIZE (10 MB) reads × timeout. A total-time deadline is a planned follow-up; today the per-IO bound covers the “goes fully silent” hazard, not the slow-trickle-but-progressing one.
• No custom request headers. Only Host, User-Agent, Accept, Accept-Encoding, Connection, and (for POST/PUT) Content-Type + Content-Length are sent. Content-Type rejects control characters in the value to prevent header injection. A header-bag API is a planned follow-up.
• No client certificate auth, ALPN selection, or peer-cert inspection. Inherited from net.tls.client.
• POST is not auto-retried on transient transport failure; GET/PUT/DELETE are (idempotent per RFC 9110). A POST that fails mid-flight surfaces as a connection error.

Regular Expressions

All regex operations return a Bool success flag (false for invalid regex).

Compression

Variant Operations

List Operations

Map Operations

Float Arithmetic

Float Comparison

Float Math

NaN/Infinity propagate per IEEE 754 — no (value Bool) flag. e.g. f.sqrt of a negative returns NaN; f.ln 0.0 returns -Infinity.

Roots / powers

Exponential / logarithmic

Trigonometric (radians)

Rounding

Constants

Test Framework

Time Operations

Serialization

Stack Introspection

Standard Library Modules

These modules are included with include std:<module-name>.

std:json - JSON Parsing

JSON parsing and serialization implemented in Seq.

include std:json

"hello" json-string json-serialize io.write-line  # "hello"
"{\"name\":\"bob\"}" json-parse drop json-serialize io.write-line

Value Constructors

Builders

Type Predicates

Extractors

Parsing & Serialization

std:yaml - YAML Parsing

YAML parsing for configuration files and data.

include std:yaml

"name: hello\nport: 8080" yaml-parse drop yaml-serialize io.write-line

Supports: key-value pairs, nested objects (indentation), strings, numbers, booleans, null, comments.

std:http - HTTP Response Helpers

Helper functions for building HTTP servers.

include std:http

"Hello, World!" http-ok   # Returns full HTTP 200 response
request http-request-path # Extract path from request

Response Building

Request Parsing

std:list - List Utilities

Convenient words for building lists.

include std:list

list-of 1 lv 2 lv 3 lv  # Build [1, 2, 3]

std:map - Map Utilities

No additional utilities beyond the built-in Map Operations.

std:imath - Integer Math

Common mathematical operations for integers.

include std:imath

-5 abs            # 5
48 18 gcd         # 6
15 0 100 clamp    # 15

For modulo and power, use the i.modulo and i.pow builtins directly (( Int Int -- Int Bool ) — see the Integer Arithmetic section above).

std:fmath - Float Math

Common mathematical operations for floats.

include std:fmath

-3.14 f.abs       # 3.14
2.5 3.7 f.max     # 3.7
1.5 f.square      # 2.25

For sqrt, trig, exp/log, rounding, and constants (f.pi, f.e, f.tau), see the Float Math builtin section above — those are always available without an include.

std:zipper - Functional List Zipper

A zipper provides O(1) cursor movement and “editing” of immutable lists by maintaining a focus element with left and right context.

include std:zipper

list-of 1 lv 2 lv 3 lv 4 lv 5 lv
zipper.from-list
zipper.right zipper.right   # focus is now 3
zipper.focus                # get current element (3)
10 zipper.set               # replace focus with 10
zipper.to-list              # [1, 2, 10, 4, 5]

Construction

Navigation

Query

Modification

std:signal - Signal Handling

Unix signal handling with a safe, flag-based API.

include std:signal

signal.trap-shutdown  # Trap SIGINT and SIGTERM

: server-loop ( -- )
  signal.shutdown-requested? if
    "Shutting down..." io.write-line
  else
    handle-request
    server-loop
  then
;

Signal Constants (builtins)

Convenience Words

std:son - Seq Object Notation Helpers

Convenience module that re-exports std:map and std:list, providing all the builder words needed for SON data construction.

include std:son

map-of "host" "localhost" kv "port" 8080 kv
list-of 1 lv 2 lv 3 lv

Including std:son gives you map-of, kv, list-of, and lv.

Security warning: SON files are executable Seq code. Only load SON from trusted sources.

std:stack-utils - Stack Utilities

Common stack operations built from primitives.

include std:stack-utils

1 2 3 2drop  # Stack: 1

Built-in operations: 152 total. Standard library modules provide additional functionality.

Seq Type System Guide

Overview

Seq has a static type system with row polymorphism that verifies your programs at compile time. The type checker ensures:

• Stack safety: Operations receive the correct types
• No stack underflow: Operations never pop from an empty stack
• Branch compatibility: Conditionals produce consistent stack effects
• Type correctness: String operations get Strings, Int operations get Ints, etc.

All type checking happens at compile time - there’s zero runtime overhead.

Stack Effect Declarations

Basic Syntax

Words declare their stack effect - how they transform the stack:

: square ( Int -- Int )
  dup i.* ;

Stack effect format: ( inputs -- outputs )

• Before --: Types expected on stack (top on right)
• After --: Types produced on stack (top on right)

Reading Stack Effects

Stack effects are read bottom-to-top, with the rightmost type being the top of stack:

: example ( Int String -- Bool )
  # Expects:  Bottom [ Int String ] Top
  # Produces: Bottom [ Bool ] Top
  ...
;

When this word is called:

• String must be on top of stack
• Int must be below the String
• After execution, a Bool will be on top

Examples

# Takes nothing, produces an Int
: forty-two ( -- Int )
  42 ;

# Takes two Ints, produces one Int
: add-numbers ( Int Int -- Int )
  i.+ ;

# Takes String, produces nothing (prints it)
: print ( String -- )
  io.write-line ;

# Takes Int and String, produces String (e.g., "Value: 42")
: format ( Int String -- String )
  swap int->string swap string.concat ;

Row Polymorphism

The Problem

How do we type dup? It should work for any type:

42 dup       # Works: Int Int
"hi" dup     # Works: String String

But it also needs to work with any stack depth:

# With empty stack
42 dup            # ( -- Int Int )

# With existing values on stack
10 20 dup         # ( Int -- Int Int Int )
"a" "b" dup       # ( String -- String String String )

The Solution: Row Variables

Row variables represent “the rest of the stack”:

: dup ( ..a T -- ..a T T )
  # ..a = whatever is already on the stack
  # T = type on top
  # Result: same stack, but top duplicated
  ...
;

Components:

• ..a - Row variable (rest of stack)
• T - Type variable (polymorphic over any type)
• Stack effect says: “Give me a stack with some stuff (..a) and a value (T) on top, I’ll give you the same stack with that value duplicated”

Row Polymorphism in Action

All stack operations use row polymorphism:

# Duplicate top value
: dup ( ..a T -- ..a T T )

# Remove top value
: drop ( ..a T -- ..a )

# Swap top two values
: swap ( ..a T U -- ..a U T )

# Copy second value to top
: over ( ..a T U -- ..a T U T )

# Rotate three values
: rot ( ..a T U V -- ..a U V T )

Built-in operations also use row polymorphism:

# Add: works at any stack depth
: i.+ ( ..a Int Int -- ..a Int )

# Print: works at any stack depth
: io.write-line ( ..a String -- ..a )

Implicit Row Polymorphism

All stack effects in Seq are implicitly row-polymorphic. You don’t need to write ..rest explicitly - the compiler adds it automatically:

# What you write:
: double ( Int -- Int )
  dup i.+ ;

# What the compiler understands:
: double ( ..rest Int -- ..rest Int )
  dup i.+ ;

This means:

• ( -- Int ) is treated as ( ..rest -- ..rest Int ) - pushes Int onto any stack
• ( Int -- ) is treated as ( ..rest Int -- ..rest ) - consumes Int from any stack
• ( Int Int -- Int ) is treated as ( ..rest Int Int -- ..rest Int ) - works at any depth

Why this matters: You can call double from any stack state:

# With one value on stack:
42 double           # 42 → 84

# With extra values below:
10 20 30 double     # 10 20 30 → 10 20 60

The values 10 and 20 are untouched—double only operates on the top. Without implicit row polymorphism, double would only work with exactly one Int on the stack—you couldn’t compose operations freely.

When to use explicit row variables:

• Use explicit ..a, ..rest when you need to name the row variable
• Useful when multiple row variables must match (e.g., in quotation types)
• Example: ( ..a T -- ..a T T ) makes it clear both sides share the same ..a

Why This Matters

Row polymorphism enables stack operation composition:

: swap-and-add ( Int Int Int -- Int Int )
  swap i.+ ;

# Type checker verifies:
# 1. swap: ( ..a Int Int -- ..a Int Int )
#    With ..a = Int, we get: ( Int Int Int -- Int Int Int )
# 2. i.+: ( ..a Int Int -- ..a Int )
#    With ..a = Int, we get: ( Int Int Int -- Int Int )
# Result: ( Int Int Int -- Int Int ) ✓

Refinement Inside Quotation Bodies

Row variables are not just placeholders for “whatever is below” — they refine to expose concrete slots when an operation needs them. This is what lets nested combinators like [ [ q ] dip ] dip type-check.

When the typechecker pops a value from a stack that’s currently a bare row variable, it introduces a fresh type variable for the popped slot and a fresh row variable for what’s still below, and records the substitution ..a := ..a' T. The constraint propagates outward as the surrounding word’s effect is inferred.

# Inside the outer quotation body, the stack starts as a fresh row
# variable. The inner `[ 50 i.+ ] dip` pops a preserved value out of
# that row, refining it to "at least one Int slot present":
[ [ 50 i.+ ] dip ]
# Body's inferred effect: ( ..r Int T -- ..r Int T )
#   - ..r Int   below the preserved slot (the [ 50 i.+ ] operates here)
#   - T         the preserved slot the inner dip exposes

The outer dip then applies this body effect to a concrete stack — unification fills ..r, Int, and T from what the caller provided.

Refinement only applies to flexible row variables. A row variable named ..rest in a user-declared signature (the parser’s convention for “the caller provides whatever’s below”) is rigid — it represents the caller’s contract, not an unknown to be refined. Popping below it is a genuine stack underflow and reports as such:

: bad ( -- )    # ..rest is rigid: the user said "no inputs"
  [ ] dip       # error: dip: expected a value below the quotation:
                #        stack underflow
;

This boundary is what keeps the inference sound — declared inputs are honored, only inferred (unconstrained) row variables refine.

Row Polymorphism vs Traditional Generics

If you’re familiar with generics from languages like Java, Rust, or TypeScript, row polymorphism may seem similar—but it solves a different problem.

Traditional Generics parameterize over individual types:

// TypeScript: generic over one type T
function identity<T>(x: T): T {
  return x;
}

// Rust: generic over type T
fn identity<T>(x: T) -> T { x }

This lets identity work with any single type. But what if you need to abstract over multiple types at once—without knowing how many?

Row Polymorphism parameterizes over sequences of types:

# Seq: polymorphic over the entire stack prefix
: dup ( ..a T -- ..a T T )

The ..a isn’t a single type—it’s zero or more types. This is essential for stack-based languages where operations must work regardless of what’s “below” them on the stack.

Comparison table:

Why generics alone aren’t enough:

Consider typing swap with only traditional generics:

// TypeScript - can type swap for exactly 2 args:
function swap<T, U>(a: T, b: U): [U, T] {
  return [b, a];
}

But this doesn’t let swap ignore extra values. In Seq:

: swap ( ..a T U -- ..a U T )

The ..a means “whatever else is on the stack stays unchanged.” You can’t express this with traditional generics—you’d need a separate swap2, swap3, etc. for each stack depth.

Row polymorphism is generics extended to type sequences. Where T abstracts over a single type, ..a abstracts over zero or more types in a specific order—each potentially different. The compiler tracks that ..a bound to Int, String, Float stays exactly Int, String, Float.

Types in Seq

Concrete Types

• Int: Integer numbers (64-bit signed)
• Float: Floating-point numbers (64-bit)
• String: Text strings
• Bool: A distinct type tracked by the type checker. Literals are true and false. Comparison and logical operations produce Bool; if requires Bool.

Type Variables

• A single uppercase letter — T, U, V, K, M, etc. — is a polymorphic type variable, abstracting over one concrete type slot.
• Multi-character uppercase identifiers (Acc, Ctx, Handle, Sokcet) are not type variables. They must be a registered concrete type or union, otherwise the type checker rejects them with a “did you mean” hint. This catches typos that previously masqueraded as polymorphism.
• Example: dup ( ..a T -- ..a T T ) works for any one value type T.

Row Variables

• ..a, ..b, ..rest: Row variables (lowercase with .. prefix)
• Represent “rest of stack” — zero or more values, in order
• Enable polymorphism over stack depth, not over a single type
• Implicit on every stack effect; write them explicitly only when you need two effects to share the same row variable

Type Errors Explained

Type Mismatch

: bad ( Int -- )
  io.write-line ;  # ERROR: io.write-line expects String, got Int

Error message:

io.write-line: stack type mismatch.
Expected (..a String), got (..a Int): Type mismatch: cannot unify String with Int

Fix: Convert Int to String first:

: good ( Int -- )
  int->string io.write-line ;

Stack Underflow

: bad ( -- )
  drop ;  # ERROR: can't drop from empty stack

Error message:

drop: stack type mismatch.
Expected (..a T), got (): stack underflow

Fix: Ensure stack has a value first:

: good ( Int -- )
  drop ;

Branch Incompatibility

: bad ( Int -- ? )
  0 > if
    42          # Produces: Int
  else
    "hello"     # Produces: String - ERROR!
  then ;

Error message:

if branches have incompatible stack effects:
then=(..a Int), else=(..a String): Type mismatch: cannot unify Int with String

Fix: Both branches must produce the same types:

: good ( Int -- String )
  0 > if
    "positive"
  else
    "non-positive"
  then ;

Unbalanced If/Then

: bad ( Int Int -- Int )
  > if
    100    # Pushes Int
  then ;   # ERROR: else branch leaves stack unchanged

Error message:

if branches have incompatible stack effects:
then=(..a Int), else=(..a): branches must produce identical stack effects

Fix: Provide else branch OR don’t push in then:

: good ( Int Int -- Int )
  > if
    100
  else
    0
  then ;

Type Checking Process

The type checker works in two passes:

Pass 1: Collect Signatures

: helper ( Int -- String ) int->string ;
: main ( -- ) 42 helper io.write-line ;

First, the checker collects all word signatures:

• helper: ( Int -- String )
• main: ( -- )

Pass 2: Verify Bodies

For each word, the checker:

1. Starts with declared input stack
2. Processes each statement, tracking stack changes
3. Verifies result matches declared output

Example for main:

Start:        ( -- )                    # Empty stack
After 42:     ( Int )                   # Pushed Int
After helper: ( String )                # Applied helper's effect
After io.write-line: ( )                   # Applied io.write-line's effect
Result:       ( )                       # Matches declared output ✓

Unification

When applying an effect like add: ( ..a Int Int -- ..a Int ) to current stack ( Int Int Int ):

1. Unify effect input with current stack:

   • Effect input: ..a Int Int
   • Current stack: Int Int Int
   • Unification: ..a = Int (row variable binds to Int)

2. Apply substitution to effect output:

   • Effect output: ..a Int
   • Substitute ..a = Int: Int Int
   • Result stack: ( Int Int )

This is how the type checker proves stack safety!

Best Practices

1. Always Declare Effects

Even though the checker can infer types, always declare effects for clarity:

# Good - clear intent
: double ( Int -- Int )
  2 i.* ;

# Discouraged - unclear what it does
: double
  2 i.* ;

2. Use Descriptive Row Variable Names

# Okay
: dup ( ..a T -- ..a T T ) ... ;

# Better - shows it's the rest of stack
: dup ( ..rest T -- ..rest T T ) ... ;

3. Check Both Branches

When using conditionals, ensure both branches produce the same effect:

: abs ( Int -- Int )
  dup 0 < if
    -1 i.*    # Negate
  else
    # Leave unchanged - implicit "do nothing"
  then ;

4. Use int->string for Conversions

: print-number ( Int -- )
  int->string io.write-line ;

Examples

Simple Math

: square ( Int -- Int )
  dup i.* ;

: pythagorean ( Int Int -- Int )
  # a^2 + b^2
  swap square    # ( a b -- b a^2 )
  swap square    # ( b a^2 -- a^2 b^2 )
  i.+ ;          # ( a^2 b^2 -- sum )

String Operations

: greet ( String -- )
  "Hello, " swap string.concat io.write-line ;

: print-number ( Int -- )
  int->string io.write-line ;

Conditionals

: max ( Int Int -- Int )
  2dup i.> if
    drop    # Keep first
  else
    nip     # Keep second
  then ;

: describe ( Int -- String )
  0 i.> if
    "positive"
  else
    "non-positive"
  then ;

Stack Shuffling

: rot-sum ( Int Int Int -- Int )
  # Sum three numbers after rotation
  rot i.+ i.+ ;

: under ( Int Int Int -- Int Int )
  # Like over but deeper
  rot swap ;

Summary

Seq’s type system provides:

• ✅ Stack safety - no underflows, no type mismatches
• ✅ Row polymorphism - stack operations work at any depth
• ✅ Implicit row polymorphism - all effects are automatically row-polymorphic
• ✅ Zero runtime cost - all checking at compile time
• ✅ Clear error messages - tells you exactly what’s wrong
• ✅ Compile-time guarantees - if it type checks, stack operations are safe

The type system is simple but powerful - it catches bugs early without getting in your way.

Happy concatenative programming! 🎉

Seq Language Grammar

This document provides a formal EBNF grammar specification for the Seq programming language.

Notation

• | - alternation
• [ ] - optional (0 or 1)
• { } - repetition (0 or more)
• ( ) - grouping
• "..." - literal terminal
• UPPERCASE - lexical tokens
• lowercase - grammar rules

Grammar

Top-Level Structure

program         = { include | union_def | word_def } ;

include         = "include" include_path ;
include_path    = "std" ":" IDENT
                | "ffi" ":" IDENT
                | STRING ;

Union Types (Algebraic Data Types)

union_def       = "union" UPPER_IDENT "{" { union_variant } "}" ;
union_variant   = UPPER_IDENT [ "{" field_list "}" ] ;
field_list      = [ field { "," field } [ "," ] ] ;
field           = IDENT ":" type_name ;

Word Definitions

word_def        = ":" IDENT [ stack_effect ] { statement } ";" ;

stack_effect    = "(" type_list "--" type_list [ "|" effect_annotation { effect_annotation } ] ")" ;
effect_annotation = "Yield" type ;
type_list       = [ row_var ] { type } ;
row_var         = ".." ROW_VAR_NAME ;

type            = base_type
                | type_var
                | quotation_type
                | closure_type ;

base_type       = "Int" | "Float" | "Bool" | "String" ;
type_var        = UPPER_IDENT ;
quotation_type  = "[" type_list "--" type_list "]" ;
closure_type    = "Closure" "[" type_list "--" type_list "]" ;

type_var must not be the literal token Quotation: the parser rejects it explicitly with a hint pointing at the [ .. -- .. ] syntax. The name Closure is also reserved — it’s handled as the start of closure_type, not as a type variable.

Statements

statement       = literal
                | word_call
                | quotation
                | if_stmt
                | match_stmt ;

literal         = INT_LITERAL
                | FLOAT_LITERAL
                | BOOL_LITERAL
                | STRING
                | SYMBOL_LITERAL ;

word_call       = IDENT ;

quotation       = "[" { statement } "]" ;

if_stmt         = "if" { statement } ( "then" | "else" { statement } "then" ) ;

match_stmt      = "match" { match_arm } "end" ;
match_arm       = pattern "->" { statement } ;
pattern         = UPPER_IDENT [ "{" { BINDING } "}" ] ;
BINDING         = ">" IDENT ;

BINDING is a single lexical token: > and the field name must not be separated by whitespace. >value is a binding; > value is two separate tokens (the word calls > and value) and the parser reports an error asking for the >-prefix form.

Lexical Grammar

Identifiers

IDENT           = IDENT_START { IDENT_CHAR } ;
IDENT_START     = LETTER | "_" | "-" | "." | ">" | "<" | "=" | "?" | "!" | "+" | "*" | "/" | "%" ;
IDENT_CHAR      = IDENT_START | DIGIT ;

UPPER_IDENT     = UPPER_LETTER { IDENT_CHAR } ;
LOWER_IDENT     = LOWER_LETTER { IDENT_CHAR } ;

ROW_VAR_NAME    = LOWER_LETTER { LETTER | DIGIT | "_" } ;

LETTER          = UPPER_LETTER | LOWER_LETTER ;
UPPER_LETTER    = "A" | "B" | ... | "Z" ;
LOWER_LETTER    = "a" | "b" | ... | "z" ;
DIGIT           = "0" | "1" | ... | "9" ;

Row-variable names (..rest) use the stricter ROW_VAR_NAME rule: they must start with a lowercase letter and contain only letters, digits, and underscores. The broader IDENT punctuation characters (`- . > < = ? !

• • / %) are rejected. The names Int, Bool, String` are reserved even though they’re already excluded by the lowercase-start rule (the parser emits a dedicated error if you try to use them).

Literals

INT_LITERAL     = DECIMAL_INT | HEX_INT | BINARY_INT ;
DECIMAL_INT     = [ "-" ] DIGIT { DIGIT } ;
HEX_INT         = "0" ( "x" | "X" ) HEX_DIGIT { HEX_DIGIT } ;
BINARY_INT      = "0" ( "b" | "B" ) BINARY_DIGIT { BINARY_DIGIT } ;

HEX_DIGIT       = DIGIT | "a" | "b" | "c" | "d" | "e" | "f"
                        | "A" | "B" | "C" | "D" | "E" | "F" ;
BINARY_DIGIT    = "0" | "1" ;

FLOAT_LITERAL   = [ "-" ] ( DIGIT { DIGIT } "." { DIGIT } [ EXPONENT ]
                          | DIGIT { DIGIT } EXPONENT
                          | "." DIGIT { DIGIT } [ EXPONENT ] ) ;
EXPONENT        = ( "e" | "E" ) [ "+" | "-" ] DIGIT { DIGIT } ;

BOOL_LITERAL    = "true" | "false" ;

SYMBOL_LITERAL  = ":" SYMBOL_NAME ;
SYMBOL_NAME     = LETTER { LETTER | DIGIT | "-" | "_" | "." | "?" | "!" } ;

(* `:` is a single-character delimiter token; whitespace after it is not
   significant. Disambiguation between `word_def` and `SYMBOL_LITERAL` is
   context-driven: a `:` at the top level starts a `word_def`, and a `:`
   inside a word body (wherever a `statement` is expected) starts a
   `SYMBOL_LITERAL`. *)

STRING          = '"' { STRING_CHAR | ESCAPE_SEQ } '"' ;
STRING_CHAR     = any character except '"' or '\' ;
ESCAPE_SEQ      = '\' ( '"' | '\' | 'n' | 'r' | 't' )
                | '\' 'x' HEX_DIGIT HEX_DIGIT ;

The \xNN escape produces the Unicode code point U+00NN. For NN in 00..7F this is a single ASCII byte (common use: \x1b for ANSI terminal escape sequences). For NN in 80..FF the code point falls in the Latin-1 Supplement block (U+0080..U+00FF) and the resulting character is encoded as multi-byte UTF-8.

Comments and Whitespace

COMMENT         = "#" { any character except newline } NEWLINE ;
SHEBANG         = "#!" { any character except newline } NEWLINE ;
WHITESPACE      = SPACE | TAB | NEWLINE ;

A SHEBANG line (typically #!/usr/bin/env seqc) is accepted anywhere a COMMENT is, so scripts can be executed directly from the shell. The parser treats it as an ordinary comment.

Comments matching the form # seq:allow(lint-id) are collected as lint allowances for the word definition that follows them. The text inside the parentheses is the lint rule id; multiple seq:allow comments before a word stack additively.

Semantic Notes

Row Polymorphism

All stack effects are implicitly row-polymorphic. When no explicit row variable is given, an implicit ..rest is assumed:

# These are equivalent:
: dup ( T -- T T ) ... ;
: dup ( ..rest T -- ..rest T T ) ... ;

This means ( -- ) preserves the stack (it’s ( ..rest -- ..rest )), not that it requires an empty stack.

Naming Conventions

For each union definition, the compiler auto-generates helper words by convention. Given union Shape { Circle { radius: Int } … }:

These are ordinary word_calls at the grammar level; they’re listed here so readers can predict the generated names.

Reserved Words

The following are reserved and cannot be used as word names:

• Control flow: if, else, then, match, end
• Definitions: union, include
• Literals: true, false

Operator Precedence

Seq has no operator precedence - all tokens are either literals or word calls. Evaluation is strictly left-to-right with stack-based semantics.

Quotations vs Closures

A quotation (the surface syntax [ … ]) has two possible types:

• quotation_type — if the body consumes only values pushed inside the quotation itself (plus an implicit row variable).
• closure_type — if the body references values from the enclosing stack. The compiler captures those values into an environment at the point the quotation is produced; the result is a Closure[ … ] at the type level.

There is no dedicated syntax for a closure — the parser always builds a quotation literal, and the type checker decides whether the result is a quotation_type or a closure_type based on what the body references.

Arithmetic Sugar

The tokens +, -, *, /, %, =, <, >, <=, >=, and <> are ordinary identifiers at the grammar level but are resolved by the compiler to their typed counterparts based on the inferred stack types. For example:

3 4 +        # resolves to `i.+` — both operands are Int
3.0 4.0 +    # resolves to `f.+` — both operands are Float

This is a compile-time rewrite, not dynamic dispatch: if the types can’t be inferred unambiguously the program fails to type-check. Writing the explicit form (i.+, f.<, etc.) is always valid and suppresses the sugar resolution.

Sugar resolves only when the operand types are visible on the typechecker’s stack at the use site. Inside a quotation body the body is typed against its own fresh effect, so its stack is empty from the resolver’s perspective and sugar cannot resolve. Use the typed form inside quotations:

3 4 [ + ] call         # error: + can't resolve, operands not in scope
3 4 [ i.+ ] call       # idiomatic — works regardless of caller context

The typed form (i.+, f.+, string.concat, …) is the always-works idiom; sugar is a top-level convenience that’s nice for short expressions but should be expanded when writing words intended to be passed to combinators like dip, keep, bi, times, or each-integer.

Examples

Complete Program

include std:json

union Result {
  Ok { value: Int }
  Error { message: String }
}

: safe-divide ( Int Int -- Result )
  dup 0 i.= if
    drop drop "Division by zero" Make-Error
  else
    i.divide drop Make-Ok
  then
;

: main ( -- )
  10 2 safe-divide
  match
    Ok { >value } -> value int->string io.write-line
    Error { >message } -> message io.write-line
  end
;

Stack Effects

# Simple transformation
: double ( Int -- Int ) 2 i.* ;

# Multiple inputs/outputs
: divmod ( Int Int -- Int Int ) over over i./ rot rot i.% ;

# Row-polymorphic (preserves rest of stack)
: swap ( ..a T U -- ..a U T ) ... ;

# Quotation type
: apply-twice ( Int [Int -- Int] -- Int ) dup rot swap call swap call ;

# Closure type
: make-adder ( Int -- Closure[Int -- Int] ) [ i.+ ] ;

Include System Design

Overview

Seq supports a simple include system for code reuse. The design prioritizes:

• Minimal filesystem exposure
• Clear provenance (stdlib vs user code)
• Collision detection with good error messages
• Future extensibility to packages

Syntax

# Standard library (ships with compiler)
include std:http
include std:imath

# FFI bindings (C library wrappers)
include ffi:libedit

# Relative to current file
include "my-utils"
include "lib/helpers"

Rules

1. std: prefix - References stdlib bundled with compiler

   • Compiler knows where stdlib lives (not user’s concern)
   • Example: include std:http loads http.seq from stdlib

2. ffi: prefix - References FFI bindings for C libraries

   • Some bindings ship with compiler (e.g., ffi:libedit)
   • Others require --ffi-manifest flag with a TOML manifest
   • Example: include ffi:libedit loads readline-style functions
   • See FFI_GUIDE.md for full documentation

3. Quoted string - Path relative to the including file

   • No absolute paths allowed
   • Paths can use .. to reference parent directories
   • Example: include "lib/foo" loads ./lib/foo.seq
   • Example: include "../src/utils" from a tests directory
   • Example: include "../../src/tokenizer" for deeper nesting

4. Extension omitted - Compiler adds .seq automatically

5. Include once - Files are included at most once per compilation

   • Duplicate includes are silently ignored
   • Prevents diamond dependency issues

Collision Detection

If the same word is defined in multiple files:

Error: Word 'http-ok' is defined multiple times:
  - stdlib/http.seq:45
  - ./my-utils.seq:12

Hint: Rename one of the definitions to avoid collision.

All definitions are still global (no namespaces), but collisions are caught at compile time.

Implementation Notes

Compilation Pipeline

1. Resolve includes - Before parsing main file:

   • Scan for include statements
   • Resolve paths (stdlib vs relative)
   • Load and parse included files
   • Recursively process their includes
   • Track included files to prevent duplicates

2. Merge programs - Combine all WordDefs into single Program

3. Check collisions - Before type checking:

   • Build map of word name -> definition location
   • Error if any word has multiple definitions

4. Continue normally - Type check and codegen as before

Stdlib Location

The compiler locates the stdlib in this order:

1. SEQ_STDLIB environment variable (if set to a valid directory)
2. stdlib/ directory relative to the compiler binary (for installed builds)
3. Embedded stdlib compiled into the binary (fallback)

Path Validation

Include paths are validated:

1. Absolute Path Rejection - Absolute paths are rejected; all includes must be relative
2. Empty Path Validation - Empty include paths are rejected
3. Canonicalization - Paths are canonicalized to resolve symlinks and normalize .. segments
4. File Must Exist - The target .seq file must exist

Examples

Simple Program

include std:http

: main ( -- Int )
  "Hello" http-ok io.write-line
  0
;

With Local Utils

include std:http
include "utils"

: main ( -- Int )
  get-greeting http-ok io.write-line
  0
;

Where utils.seq in same directory:

: get-greeting ( -- String )
  "Hello from utils!"
;

Collision Error

include std:http
include "my-http"   # Also defines http-ok

Error: Word 'http-ok' is defined multiple times:
  - stdlib/http.seq:45
  - ./my-http.seq:3

Weaves: Generators and Coroutines

Weaves are Seq’s implementation of generators/coroutines, built on top of the CSP-style strand system. They provide bidirectional communication between a producer and consumer through structured yield/resume semantics.

Why Weaves?

Generators are useful when you need to:

• Produce values lazily (only compute when needed)
• Maintain state between iterations without explicit data structures
• Transform streams of data with backpressure
• Implement query engines or interpreters that yield results incrementally

Seq’s weaves are unique in that they’re built on the same strand/channel infrastructure as CSP concurrency. A weave is essentially a strand with a structured protocol for yield and resume.

Basic Concepts

Core Operations

Simple Counter Example

A counter that yields its current value and accepts an increment:

# Counter - yields current count, receives increment
: counter ( Ctx Int -- | Yield Int )
  tuck           # ( count Ctx count )
  yield          # yield count, receive increment -> ( count Ctx increment )
  rot            # ( Ctx increment count )
  i.add          # ( Ctx new_count )
  counter        # tail recurse
;

: main ( -- )
  # Create weave
  [ counter ] strand.weave        # ( handle )

  # Resume with initial value 10
  10 strand.resume                # ( handle yielded has_more )
  drop                            # ( handle yielded )
  "First: " swap int->string string.concat io.write-line
                                  # ( handle )

  # Resume with increment 5
  5 strand.resume                 # ( handle yielded has_more )
  drop
  "After +5: " swap int->string string.concat io.write-line

  strand.weave-cancel             # Clean up (infinite generator)
;

Output:

First: 10
After +5: 15

The Ctx Threading Pattern

Critical: The weave context (Ctx) must be explicitly threaded through your code. This is different from languages where generator state is implicit.

The quotation passed to strand.weave receives (Ctx, first_resume_value) and must keep the Ctx accessible for yield calls:

# WRONG - loses the Ctx
: bad-generator ( Ctx Int -- | Yield Int )
  yield          # Error: Ctx is buried under Int
;

# CORRECT - Ctx is on top for yield
: good-generator ( Ctx Int -- | Yield Int )
  tuck           # ( Int Ctx Int )
  yield          # ( Int Ctx resume_value )
  ...
;

Handling Weave Completion

strand.resume returns ( handle value has_more ). The boolean indicates whether the weave yielded (true) or completed (false):

: finite-generator ( Ctx Int -- | Yield Int )
  dup 0 i.<= if
    drop drop    # Done - just return, weave ends
  else
    tuck yield   # Yield current value
    rot 1 i.-    # Decrement
    finite-generator
  then
;

: main ( -- )
  [ finite-generator ] strand.weave
  3 strand.resume    # ( handle 3 true )
  drop drop          # ( handle )
  0 strand.resume    # ( handle 2 true )
  drop drop
  0 strand.resume    # ( handle 1 true )
  drop drop
  0 strand.resume    # ( handle 0 false ) - weave completed!
  if
    "More values" io.write-line
  else
    drop "Weave finished" io.write-line
  then
  drop  # drop handle
;

Resource Management

Weaves hold resources (channels internally). You must either:

1. Resume to completion - Keep resuming until has_more is false
2. Cancel explicitly - Call strand.weave-cancel to release resources

# BAD - resource leak!
[ infinite-generator ] strand.weave
10 strand.resume drop drop drop  # Weave abandoned, resources leak

# GOOD - explicit cancellation
[ infinite-generator ] strand.weave
10 strand.resume drop drop
strand.weave-cancel              # Clean up

The linter will warn about immediate drops of weave handles.

Type System Integration

The Yield effect appears in stack effect annotations:

: my-generator ( Ctx Int -- | Yield Int )
  #                      ^^^^^^^^^^^ Yield effect
  ...
;

This tells the type checker that the word participates in generator semantics. The effect propagates through callers.

Advanced: Structured Data

Weaves work well with union types for rich producer/consumer protocols:

union SensorReading {
  Reading { temp: Int, status: String }
}

: sensor-processor ( Ctx SensorReading -- | Yield SensorReading )
  # Transform the reading
  dup 0 variant.field-at    # Get temp
  classify-temp             # Classify it
  swap 1 variant.field-at   # Get status
  Make-Reading              # Create new reading

  swap yield                # Yield result, get next reading
  sensor-processor          # Process next
;

Comparison to Other Languages

Backpressure

Weaves provide backpressure through the pull model: a producer cannot advance past yield until the consumer explicitly calls strand.resume. The producer is suspended at yield, not running ahead buffering values — it is physically blocked waiting for a resume signal.

This means the consumer controls the production rate with no additional coordination needed:

# Infinite data source - but only computes on demand
: data-source ( Ctx Int -- | Yield Int )
  tuck yield        # Block here until consumer is ready
  rot 1 i.+
  data-source
;

: slow-consumer ( WeaveCtx -- )
  # Only pulls the next item when ready to process it
  0 strand.resume   # Producer runs exactly one step
  drop              # Process the value
  # ... do slow work ...
  slow-consumer
;

This is not buffered backpressure (as in Reactive Streams or Akka Streams, where a downstream signals demand counts). It is stricter: one resume produces exactly one yielded value. The producer cannot run ahead at all.

When to Use Weaves vs Strands

See Also

• Concurrency - Strands and channels
• examples/weave/ - Working examples

Tail Call Optimization (TCO) Guide

Overview

This guide describes tail call optimization in seqc, the Seq compiler. TCO is a critical optimization for functional and recursive programming styles, allowing recursive functions to execute in constant stack space.

Motivation

The Problem

Without TCO, recursive functions consume stack space for each call:

: factorial ( Int -- Int )
    dup 1 i.<= if
        drop 1
    else
        dup 1 i.- factorial i.*   # Each call adds a stack frame
    then
;

Calling 1000 factorial would create 1000 stack frames, risking stack overflow.

Why TCO Matters for Seq

1. Concatenative languages favor recursion - Without built-in loop constructs, recursion is the natural way to express iteration in Seq

2. SeqLisp and embedded languages - Languages implemented in Seq (like SeqLisp) have recursive interpreters. Without TCO, both the interpreter recursion AND user program recursion compound

3. Coroutine stack limits - Strands have fixed stacks (128KB by default, configurable via SEQ_STACK_SIZE). TCO reduces pressure on these stacks

4. Differentiating feature - Many compiled languages lack guaranteed TCO. Making it a first-class feature positions Seq for functional programming use cases

Background: How TCO Works

Traditional Call

caller:
    push return_address
    push arguments
    jump to callee

callee:
    ... do work ...
    pop arguments
    pop return_address
    jump to return_address

Tail Call (Optimized)

When a call is the last thing before returning, we can reuse the current frame:

caller:
    # Don't push return address - reuse caller's
    overwrite arguments in place
    jump to callee  # callee will return directly to our caller

LLVM Support

Seq uses LLVM’s musttail calling convention — guaranteed TCO (compiler error if the optimization is impossible):

%result = musttail call ptr @seq_bar(ptr %stack)
ret ptr %result

All Seq word functions share a uniform ptr -> ptr signature, which is ideal for musttail: return value is directly from the call with no cleanup between.

Tail Position in Seq

A call is in tail position when it’s the last operation before the function returns. In Seq’s word-based model:

Tail position:

: foo ( -- )
    setup-stuff
    bar           # Last word - tail position
;

NOT tail position:

: foo ( -- Int )
    something
    bar           # Not tail - result used by i.+
    i.+
;

Conditionals

Both branches must end in tail position for the call to be a tail call:

: factorial ( Int -- Int )
    dup 1 i.<= if
        drop 1        # Base case - not a call, that's fine
    else
        dup 1 i.-
        factorial     # Tail position in else branch
        i.*           # PROBLEM: i.* comes after factorial
    then
;

This common pattern is NOT tail-recursive. To enable TCO, use accumulator style:

: factorial-acc ( Int Int -- Int )
    over 1 i.<= if
        nip           # Return accumulator
    else
        swap dup 1 i.- swap
        rot i.*       # Multiply first
        factorial-acc # NOW in tail position
    then
;

: factorial ( Int -- Int )
    1 factorial-acc
;

Match Expressions

Match expressions work the same as conditionals - each arm body is independently checked for tail position. If a match arm’s last statement is a recursive call, it gets TCO:

: process-list ( SexprList -- Int )
  match
    SNil ->
      0                    # Base case, no recursion
    SCons { >head >tail } ->
      swap do-something    # Not tail position (head on stack)
      process-list         # Last statement - gets TCO ✓
  end
;

Each arm is evaluated independently, so different arms can have different tail call behavior:

: eval-expr ( Expr -- Value )
  match
    Literal { >value } ->
      # value on stack
                           # No recursion needed
    BinOp { >left >op >right } ->
      # Stack: ( left op right )
      rot eval-expr        # NOT tail - result used below
      swap eval-expr
      apply-op
    Call { >func >args } ->
      # Stack: ( func args )
      eval-args
      eval-expr            # Last statement - gets TCO ✓
  end
;

The key insight: TCO applies to the last statement in each arm body, regardless of how many statements precede it.

Mutual Recursion

Mutual recursion works correctly — each tail call reuses the caller’s frame regardless of which function is called:

: even? ( Int -- Bool )
    dup 0 i.= if drop true else 1 i.- odd? then
;

: odd? ( Int -- Bool )
    dup 0 i.= if drop false else 1 i.- even? then
;

1000000 even? runs in constant stack space despite bouncing between two words.

Design Decisions

1. TCO is always-on

   • No opt-in required — compiler applies TCO whenever possible
   • Rationale: Coroutine stacks are fixed-size (128KB default), recursion is idiomatic
   • Trade-off: Shorter stack traces in errors (acceptable)

2. No @tailrec annotation

   • Compiler silently optimizes when possible
   • No warnings for non-tail-recursive code
   • Rationale: Keep language simple, avoid annotation clutter

Appendix: LLVM IR Examples

Before TCO

define ptr @seq_factorial(ptr %stack) {
entry:
    ; ... check n <= 1 ...
    br i1 %cond, label %base, label %recurse

base:
    ; return 1
    %result1 = call ptr @patch_seq_push_int(ptr %stack2, i64 1)
    ret ptr %result1

recurse:
    ; recursive case
    %n_minus_1 = call ptr @patch_seq_subtract(ptr %stack3)
    %rec_result = call ptr @seq_factorial(ptr %n_minus_1)  ; NOT tail call
    %final = call ptr @patch_seq_multiply(ptr %rec_result)
    ret ptr %final
}

After TCO (Accumulator Style)

define ptr @seq_factorial_acc(ptr %stack) {
entry:
    ; ... check n <= 1 ...
    br i1 %cond, label %base, label %recurse

base:
    ; return accumulator (already on stack)
    ret ptr %stack2

recurse:
    ; compute new acc, new n
    %new_stack = call ptr @patch_seq_multiply(ptr %stack3)
    %prepared = call ptr @patch_seq_subtract(ptr %new_stack)
    %result = musttail call ptr @seq_factorial_acc(ptr %prepared)
    ret ptr %result
}

References

• LLVM Language Reference: Tail Calls
• LLVM Tail Call Optimization
• Wikipedia: Tail Call

Foreign Function Interface (FFI) Guide

Overview

Seq’s FFI system enables calling external C libraries from Seq programs. FFI is purely a compiler/linker concern - the runtime remains free of external dependencies, preserving Seq’s minimal footprint.

Quick Start

Built-in FFI: libedit

The compiler includes a BSD-licensed libedit binding for readline-style input:

include ffi:libedit

: main ( -- Int )
  "prompt> " readline
  "You entered: " swap string.concat io.write-line
  0
;

Build with:

seqc build myprogram.seq -o myprogram

External FFI: SQLite

For libraries not bundled with the compiler, use --ffi-manifest:

include ffi:sqlite

: main ( -- Int )
  ":memory:" db-open drop
  "CREATE TABLE test (id INT)" db-exec drop
  db-close drop
  0
;

Build with:

seqc --ffi-manifest sqlite.toml myprogram.seq -o myprogram

Include Syntax

FFI bindings are accessed via the ffi: prefix in include statements:

include ffi:libedit    # Built-in manifest (ships with compiler)
include ffi:sqlite     # Must provide --ffi-manifest sqlite.toml

The library name after ffi: must match the name field in the manifest.

Writing FFI Manifests

FFI bindings are declared in TOML files. Here’s a complete example:

[[library]]
name = "mylib"
link = "mylib"           # Passed to linker as -lmylib

[[library.function]]
c_name = "my_function"   # C function name
seq_name = "my-func"     # Seq word name
stack_effect = "( Int String -- Int )"
args = [
  { type = "int", pass = "int" },
  { type = "string", pass = "c_string" }
]
[library.function.return]
type = "int"

Type Mappings

Pass Modes

The pass field controls how arguments are passed to C:

Memory Ownership

The ownership field on returns controls memory management:

Advanced Features

Out Parameters (by_ref)

Some C functions return values via pointer parameters (out params). Use by_ref pass mode:

[[library.function]]
c_name = "sqlite3_open"
seq_name = "db-open"
stack_effect = "( String -- Int Int )"   # db handle + return code
args = [
  { type = "string", pass = "c_string" },
  { type = "ptr", pass = "by_ref" }       # Out parameter
]
[library.function.return]
type = "int"

For by_ref arguments:

1. Compiler allocates local storage
2. Passes pointer to that storage to C function
3. After call, reads value and pushes onto stack

Important: The by_ref value is an opaque handle owned by the C library. You must:

• Only pass it to functions from the same library
• Never attempt to free it manually
• Always use the library’s cleanup function (e.g., db-close)

Fixed Value Arguments

For arguments that should always be a constant (like NULL callbacks):

args = [
  { type = "ptr", pass = "ptr" },
  { type = "string", pass = "c_string" },
  { type = "ptr", value = "null" },    # Always passes NULL
  { type = "ptr", value = "null" },
  { type = "ptr", value = "null" }
]

Fixed value arguments don’t consume stack values - they’re compiled as constants. Supported values: null, NULL, or integer literals.

Multiple Manifests

You can load multiple FFI manifests:

seqc --ffi-manifest db.toml --ffi-manifest crypto.toml program.seq -o program

Safety Model

FFI is inherently unsafe - you’re calling into C code that can do anything. Seq’s approach:

1. Opt-in boundary: Using include ffi:* is the explicit safety boundary
2. Stack effects enforced: Type checker validates declared effects
3. Memory managed by codegen: Ownership annotations prevent leaks
4. Linker flag validation: Only safe characters allowed in link names

If you don’t use FFI, your Seq program has full memory safety.

Security Considerations

• Trust your manifests: Malicious manifests could link arbitrary libraries
• Validate external manifests: Review manifests before using --ffi-manifest
• Linker injection prevented: Link names can only contain alphanumeric, dash, underscore, and dot characters

Built-in Libraries

ffi:libedit

BSD-licensed readline alternative. Provides:

Examples

Example: Interactive REPL

include ffi:libedit

: repl ( -- )
  "seq> " readline
  dup string.length 0 i.> if
    dup add-history
    process-input      # Your processing here
    repl
  else
    drop
  then
;

: main ( -- Int )
  "Welcome to Seq REPL" io.write-line
  repl
  0
;

Example: Persistent History

include ffi:libedit

: repl ( -- )
  "seq> " readline
  dup string.length 0 i.> if
    dup add-history
    process-input
    repl
  else
    drop
  then
;

: main ( -- Int )
  # Load history at startup (ignore error if file doesn't exist)
  "/tmp/.myapp_history" read-history drop

  "Welcome to Seq REPL" io.write-line
  repl

  # Save history on exit
  "/tmp/.myapp_history" write-history drop
  0
;

Note: File paths are passed directly to the C library. Shell expansions like ~ are not performed. Use os.home-dir and os.path-join to build paths from the home directory rather than hardcoding /tmp paths.

Example: SQLite Database

See examples/ffi/sqlite/ for a complete SQLite example demonstrating:

• by_ref out parameters for database handles
• Fixed null values for unused callbacks
• Proper handle cleanup with db-close

Troubleshooting

“Unknown word: readline”

Ensure you have include ffi:libedit at the top of your file.

“Unknown FFI library: sqlite”

You need to provide the manifest: --ffi-manifest path/to/sqlite.toml

Linker errors

Install the C library’s development package:

• macOS: brew install <library>
• Ubuntu: apt install lib<library>-dev
• Fedora: dnf install <library>-devel

“Invalid character in linker flag”

Link names can only contain: a-z, A-Z, 0-9, -, _, .

This prevents command injection attacks via malicious manifests.

Design Notes

Callbacks (Shelved)

FFI callbacks (C functions calling back into Seq) were explored but shelved for now.

Why shelved:

• Most useful callback patterns (qsort comparators, iteration handlers) pass pointers to the callback, requiring low-level memory operations to interpret them
• Those low-level operations (ptr-read-i64, etc.) are too invasive for Seq’s design
• Many C APIs have non-callback alternatives (e.g., SQLite’s prepared statement API works without callbacks)

Callbacks may be revisited when there’s a concrete use case that justifies the complexity.

See ROADMAP.md for the full FFI roadmap.

Observability Guide

Seq provides three layers of runtime observability for compiled programs, from zero-cost live inspection to compile-time instrumentation. All features are gated behind the diagnostics Cargo feature (enabled by default).

Quick Reference

SIGQUIT Diagnostic Dump

Send SIGQUIT to a running Seq process to dump runtime statistics to stderr without stopping it. This works like a JVM thread dump.

kill -3 <pid>

Output includes:

• Strand statistics — active, total spawned, total completed, peak (high-water mark)
• Active strand details — strand IDs and how long each has been running
• Memory statistics — arena bytes across all threads
• Warnings — lost strands (panic/abort), registry overflow

Example output:

=== Seq Runtime Diagnostics ===
Timestamp: SystemTime { ... }

[Strands]
  Active:    3
  Spawned:   150 (total)
  Completed: 147 (total)
  Peak:      12 (high-water mark)

[Active Strand Details]
  Registry capacity: 1024 slots
  3 strand(s) tracked:
    [ 1] Strand #1        running for 42s
    [ 2] Strand #148      running for 3s
    [ 3] Strand #150      running for 0s

[Memory]
  Tracked threads: 4
  Arena bytes:     2.50 MB (across all threads)

=== End Diagnostics ===

The signal handler runs on a dedicated thread using signal-hook’s iterator API, so all I/O operations happen outside signal context.

Watchdog

The watchdog detects strands that run too long without yielding, helping catch infinite loops and runaway computation in production.

Configuration

Usage

# Warn if any strand runs longer than 30 seconds
SEQ_WATCHDOG_SECS=30 ./my-program

# Check every 10 seconds instead of every 5
SEQ_WATCHDOG_SECS=30 SEQ_WATCHDOG_INTERVAL=10 ./my-program

# Exit the process if a strand is stuck (for unattended services)
SEQ_WATCHDOG_SECS=60 SEQ_WATCHDOG_ACTION=exit ./my-program

When the watchdog triggers with warn action, it dumps the same diagnostics as kill -3. With exit action, it dumps diagnostics then terminates the process.

The watchdog runs on a dedicated thread and scans the strand registry periodically. It piggybacks on existing strand tracking infrastructure, adding no overhead to the hot path.

At-Exit Report (SEQ_REPORT)

Batch programs exit before anyone can send kill -3. The at-exit report dumps KPIs automatically when the program finishes, controlled by the SEQ_REPORT environment variable.

Configuration

Usage

# Human-readable report on stderr
SEQ_REPORT=1 ./my-program

# JSON report on stderr (pipe to jq, etc.)
SEQ_REPORT=json ./my-program 2>report.json

# JSON report written directly to a file
SEQ_REPORT=json:/tmp/report.json ./my-program

# Human report with per-word call counts (requires --instrument)
SEQ_REPORT=words ./my-program

Example Output

=== SEQ REPORT ===
Wall clock:      127 ms
Strands spawned: 42
Strands done:    42
Peak strands:    8
Worker threads:  4
Arena current:   0 bytes
Arena peak:      524288 bytes
Messages sent:   100
Messages recv:   100
==================

Metrics

Instrumentation (--instrument)

The --instrument compiler flag bakes per-word atomic counters into the binary. Each time a word is called, its counter increments. This is useful for profiling which words are hot paths.

Usage

# Compile with instrumentation
seqc build --instrument my-program.seq

# Run with word-count report
SEQ_REPORT=words ./my-program

How It Works

When --instrument is passed:

1. The compiler emits a global array of i64 counters (one per word)
2. Each word’s entry point gets a single atomicrmw add monotonic instruction
3. At program startup, the counter array and word name table are registered with the runtime
4. At exit, SEQ_REPORT reads the counters and includes them in the report