Fixed gaps embedded:

Typing: static with inference
Variables can change type: no
Optional explicit types: yes

ARCHITECTURE.md

WalkLang Architecture

WalkLang is a compiled, general-purpose language for readable native programs on any OS.

main.walk -> lexer -> parser -> typed IR -> C -> native executable

Example:

# main.walk
out: 'hello'

Build shape:

main.walk -> main.c -> main / main.exe

---

1. Identity

Name: WalkLang
Ext:  .walk
Kind: compiled
Target: C
Output: native executable
VM: no
GC: no public v1.1 promise

Purpose:

Readable source.
Native output.
Small rules.
No syntax ideology maze.

Example:

var: a = 5
var: b = 10
out: + a b

Means:

create a
create b
print a + b

Core text IO stays small:

var: name = in: 'Name? '
out: name

in: reads one required stdin line. Larger IO surfaces belong in explicit modules. Draft side-effect module calls go through do: so effects remain visible:

imp: io

do: io.write('Loading')
do: io.write_line('done')

---

2. Design Priorities

Order matters:

1. readability
2. speed
3. simplicity
4. safety
5. flexibility

Example:

var: result = * (+ a b) (- c d)

Preferred over:

dense precedence tricks

WalkLang chooses visible structure over clever syntax.

---

3. Language Shape

WalkLang v1.1 is:

procedural first
limited functional
not OOP
not class-based
not inheritance-based

Example:

func: add(a int, b int) int
    return: + a b

out: add(2, 3)

Not v1.1:

class: Person       # error in v1.1

v2 adds structs, methods, and simple generic functions for composition without classes or inheritance.

---

4. Syntax Model

Core visual rules:

blocks: indentation
commands: keyword:
math: prefix
calls: name(a, b)
strings: 'single quotes'
lines: newline-terminated
grouping: (), []

Example:

if: > score 90
    out: 'A'
else:
    out: 'not A'

No braces, no semicolons:

if: > score 90 { out: 'A'; }   # error

---

5. Type Model

WalkLang v1.1 is statically typed.

Types are inferred unless written.

var: age = 25        # inferred int
var: score float = 9 # explicit float

age = 26             # ok
age = 'old'          # error: int name cannot hold string

Rule:

A name gets one type at declaration.
That type never changes.

---

6. Core Types

int
float
bool
string
array
null
function
struct (experimental in v2)

Example:

var: count = 10
var: price = 3.14
var: ok = true
var: name = 'Walker'
var: nums = [1, 2, 3]

Null needs a nullable type:

var: nickname string? = null
nickname = 'scwlkr'

Invalid:

var: nickname = null    # error: unknown nullable type

---

7. Memory Model

WalkLang has no public memory syntax.

No malloc.
No free.
No pointers in source.
No GC promise.

Memory is internal to compiler/runtime output.

Example:

var: names = ['a', 'b', 'c']
out: names[0]

The user writes array logic, not allocation logic.

v5 makes array storage explicit inside generated C:

array literals allocate item storage through the generated walk runtime helper
array item storage is owned for the process lifetime
arrays can be returned from functions without pointing at expired stack storage

This is still not source-level memory management. WalkLang programs do not call malloc, free, or pointer APIs.

---

8. Modules

Imports use namespaces.

imp: math

out: math.sqrt(9)

Exports name public values.

# calc.walk
func: square(x int) int
    return: * x x

exp: square

Use:

imp: calc

out: calc.square(4)

v1 module loading is file-local:

main.walk imp: calc -> calc.walk
calc.square -> generated C symbol calc__square

v3 package imports are still module imports, but the module name is dotted and resolved through the package cache:

imp: geometry.core

out: geometry.core.double(3)

Resolution shape:

walk.toml [dependencies] geometry = "0.1.0"
walk package resolve <registry>
walk.lock verifies geometry@0.1.0
.walk/packages/geometry/0.1.0/src/geometry/core.walk
geometry.core.double -> generated C symbol geometry__core__double

---

9. Standard Library

v1.3 stable libraries:

math
string
array
time
random
testing

Example:

imp: math
imp: random

var: x = random.int(1, 10)
out: math.sqrt(x)

testing.assert(bool) is stable as a namespaced assertion helper for walk test.

Draft library areas are not stable until they appear in docs/STDLIB.md and pass conformance tests.

file
json
matrix

---

10. Error Model

v1.1 has compiler errors, warnings, and native runtime stops.

Compile error:

var: age = 25
age = 'old'

Diagnostic:

main.walk:2:1
type error: age is int, got string

Runtime stop:

var: x = / 5 0

Diagnostic:

runtime error: divide by zero

No v1.1 recovery:

try:          # error in v1.1
catch:

---

11. Tooling Architecture

v0:

compiler
formatter
clear errors

v0.1:

test runner
basic REPL

v1:

module loader
warning levels
release build flags
cross-platform CLI release script

v1.1:

stable contract docs
pass/fail conformance fixtures
generated C snapshots
current status doc

v4:

language server
editor integration
docs generator
debug map

v5:

small generated C runtime layer
process-lifetime array storage
source comments in generated C
optimized native release builds
runtime/backend contract docs

Current IO groundwork:

do: effect statements
draft io/process modules
built-in API registry for new IO functions
process-lifetime runtime-created strings
fail-stop policy until recoverable IO results exist
UTF-8 text IO before binary IO

Later:

debugger
reference site
playground
advanced backends

Formatter example:

var:nums=[1,2,3]

Becomes:

var: nums = [1, 2, 3]

---

12. Non-Negotiables

WalkLang must feel:

readable
consistent
explicit
professional
command-oriented
common-sense natural

WalkLang must not become:

symbol soup
magic-heavy
overly implicit
visually noisy
ideology-heavy
hard to explain

Example of accepted style:

func: total(a int, b int, fee int) int
    return: + a b fee

Rejected style:

clever symbols that save 3 chars but cost understanding