# DARKOZA Language Specification — Stage 0

**Version:** 0.2.0-alpha.1  
**Status:** executable development alpha; not production-approved.

## 1. Design objectives

DARKOZA is an independent, statically typed, compiled language. Its current
runtime target is a versioned stack bytecode. The design prioritizes
deterministic behavior, explicit typing, bounded resource use and a small
trusted execution surface.

## 2. Modules and functions

A source file is UTF-8 text. A module begins with:

    module example;

Functions have typed parameters and an explicit return type:

    fn greet(name: Text) -> Text {
        return "Hello, " + name;
    }

    fn main(name: Text) -> Text {
        return greet(name);
    }

The module must define main. The CLI provides main parameters as a JSON object
whose keys and scalar types exactly match the declared parameters.

## 3. Types

- Int — signed 64-bit integer.
- Float — finite floating-point value.
- Bool — true or false.
- Text — UTF-8/Unicode text.

There are no implicit conversions. Int / Int returns Float. The plus operator
concatenates two Text values or adds numeric values. Integer overflow and
non-finite floating-point results are rejected.

## 4. Statements and expressions

Statements:

- let name = expression; or let name: Type = expression;
- return expression;
- if condition { ... } else { ... }

Expressions support scalar literals, local names, function calls, parentheses,
unary - and !, arithmetic + - * / %, comparisons == != < <= > >=, and boolean
&& ||. Boolean operators short-circuit.

Every function must return on every control-flow path. Local bindings are
immutable. Branch blocks have lexical scope. Loops, mutation, arrays, records,
generics, imports, exceptions, async, reflection and foreign-function calls
are not part of this alpha.

## 5. Core standard library

The core functions are compiler-recognized and always in scope:

- len(Text) -> Int: Unicode code-point count.
- to_text(scalar) -> Text: scalar-to-text conversion.
- abs(Int|Float) -> same numeric type; signed Int overflow remains an error.
- min(T,T), max(T,T) -> T: T must be the same numeric type.
- clamp(value, lower, upper) -> T: same numeric type; lower must not exceed upper.
- sqrt(Int|Float) -> Float: input must be non-negative.
- contains(Text, Text), starts_with(Text, Text), ends_with(Text, Text) -> Bool.

The standard library is intentionally small. It has no filesystem, networking,
process, clock, random or host environment functions.

## 6. Compilation and bytecode

The compiler performs tokenization, parsing, static type checking and bytecode
generation. Bytecode uses the DKZ-BYTECODE envelope with a SHA-256 digest.
Version 2 adds standard-library opcodes. The loader continues to accept version
1 programs; v1 bytecode cannot use v2-only instructions.

The digest detects accidental or unsophisticated modification. It is not a
digital signature and does not authenticate the publisher.

## 7. Resource limits

The Stage-0 VM enforces limits including: 1 MB source, 100,000 tokens, 1,024
functions, 256 locals per function, 100,000 instructions per function,
1,000,000 instructions per execution, 64 nested calls and 1 MB per text value.
The implementation is authoritative for exact limits.

## 8. Toolchain

The unified CLI is `bin/dkz`; the legacy `bin/dkzc` remains available.
Commands are documented in TOOLCHAIN.md. Debugger breakpoints address
function-local bytecode instruction indexes, not source lines.

## 9. Implementation and maturity

The compiler and VM are Stage-0 bootstrap code written in Python. A
DARKOZA-authored compiler, verified self-compilation, native backend, formal
verification and independent security audit have not been completed. This
alpha is not production-approved and is not a sandbox for hostile code.

## 10. Roadmap and production gates

1. Expand property-based, fuzz and differential tests.
2. Extend source locations and structured diagnostic spans.
3. Add modules/import linking and dependency resolution only with a reviewed
   capability and package trust model.
4. Implement a DARKOZA-authored Stage-1 compiler and demonstrate Stage-1/Stage-2
   agreement with reproducible builds.
5. Add native compilation only after measured workload evidence.
6. Complete independent security review, resource exhaustion tests,
   reproducible-build checks, rollback drills and an isolated worker design
   before any hosted execution.
