# DARKOZA Language

**Release:** 0.2.0-alpha.1  
**Date:** 2026-11-12  
**Status:** executable development alpha; not production-approved.

DARKOZA is an independent, statically typed programming language with its own
grammar, parser, type checker, compiler, versioned bytecode, bounded virtual
machine and developer toolchain.

## Quick start

From the language project directory:

    bin/dkz version
    bin/dkz check examples/hello.dkz
    bin/dkz run examples/hello.dkz --inputs '{"name":"Darkoza"}'
    bin/dkz build examples/hello.dkz -o build/hello.dkb
    bin/dkz exec build/hello.dkb --inputs '{"name":"Darkoza"}'

## Unified developer tools

    bin/dkz debug examples/hello.dkz --inputs '{"name":"Darkoza"}'
    bin/dkz debug examples/hello.dkz --trace
    bin/dkz fmt examples/hello.dkz
    bin/dkz fmt examples/hello.dkz --check
    bin/dkz test
    bin/dkz pkg init sample_app
    bin/dkz pkg validate
    bin/dkz pkg pack
    bin/dkz doc examples/hello.dkz -o docs/api.md

The legacy `bin/dkzc` compiler command remains available. `bin/dkzg` is a
separate experimental Arrival Graph prototype, not the DKZ language runtime.

## Architecture

1. UTF-8 lexer and parser with a compact, explicit grammar.
2. Static type checking for Int, Float, Bool and Text.
3. Compiler targeting DKZ-BYTECODE v2; v1 bytecode remains loadable.
4. SHA-256 integrity envelope for bytecode and package files.
5. Bounded stack VM with checked integer arithmetic, finite-float checks,
   instruction fuel, local/code/text limits and bounded call depth.
6. Standard-library core intrinsics for scalar math and text operations.
7. One CLI for build/run/debug/test/format/package/API docs.

## Standard library

The current core includes len, to_text, abs, min, max, clamp, sqrt, contains,
starts_with and ends_with. Signatures and edge behavior are in stdlib/README.md.

## Package manager

The package manager is offline-first. It creates and validates dkz.toml
projects, builds .dkzp source bundles, checks SHA-256 manifests and installs
archives atomically under .dkz/packages. This alpha has no online registry,
signature/trust model, dependency solver or import linker; [dependencies]
must remain empty.

## Runtime and trust boundary

The Stage-0 compiler and VM are implemented in Python. The compiler is not
self-hosted; no Stage-1/Stage-2 self-compilation has been demonstrated. The
runtime is not formally verified, independently audited, memory-safe native
code or a hostile multi-tenant sandbox. Checksums are not publisher signatures.
No hosted public code-execution endpoint is enabled.

Do not use this alpha for production secrets, payment authorization, privileged
services or untrusted multi-tenant code. No performance superiority is claimed
without controlled representative benchmarks.

## Verification

Run `bin/dkz test -q` from any working directory. The suite covers compiler
semantics, VM limits, bytecode compatibility, standard-library intrinsics,
debug tracing, formatter idempotence and package archive safety. See
RELEASE-REPORT.md and SHA256SUMS.txt for this release's evidence.
