OsakaProgrammingLanguage 0.1.1

Osaka Programming Language CLI (interpreter + VM + equivalence lock)

OsakaProgrammingLanguage (Osaka Lang)

Osaka Lang is a custom programming language runtime written in Python with:

• an AST interpreter
• a bytecode compiler + VM
• an equivalence lock for interpreter/VM behavior checks

The package exposes the CLI command:

osaka

---

Installation

From PyPI (recommended)

python3 -m pip install --upgrade OsakaProgrammingLanguage

Verify:

osaka --help

From TestPyPI

python3 -m pip install --index-url https://test.pypi.org/simple/ \
  --extra-index-url https://pypi.org/simple \
  OsakaProgrammingLanguage

From local source (development)

python3 -m pip install --upgrade "/absolute/path/to/Osaka Lang"

---

Quick Start

Run a file:

osaka examples/hello.saka

Run with debug:

osaka --debug examples/hello.saka

Start REPL:

osaka --repl

If a program emits no output, Osaka prints:

Tip: Use --debug for traces

---

CLI Reference

• --no-lock — disable equivalence lock
• --vm-only — run VM path only
• --interpreter-only — run interpreter path only
• --lock-strict — fail on lock mismatch
• --warnings-as-errors — treat warnings as errors in checks
• --debug — enable parse and execution trace verbosity
• --show-lexer-tokens — print lexer tokens
• --repl — interactive interpreter REPL

---

Language Semantics (Technical)

Kind system

Every runtime value has a kind:

• truth (authoritative)
• grain (uncertain)

Declarations:

• truthaboutgrain x = ...;
• grainsoftruth x = ...;

For arithmetic/concat/comparison flows, results are generally truth only when both operands are truth; otherwise they degrade to grain.

Control-flow constraints

if and while conditions must evaluate to truth at runtime. Grain conditions raise runtime errors (for example while-condition must be truthaboutgrain).

Mutation governance

• Ah(x) — acknowledge variable before mutation
• youknowsealsright(x) — assumption marker for mutation pathway
• Ivebeengot(x) — legacy lockout (blocks writes)
• Hecho(x) — freeze finalized variable

Current behavior includes warnings for mutation without acknowledgement and hard blocks for legacy/frozen variables.

Functions

Both syntaxes are accepted:

function add(a, b) { return a + b; }
func add2(a, b) { return a + b; }

Current interpreter rule: function parameters are bound as grain in function scope unless promoted.

Collections

• Lists: [1, 2, 3]
• Maps: {"k": 1}
• Index read/write: arr[i], arr[i] = v, m["k"]

Built-ins:

• len, keys, values, contains
• push, pop, slice

Runtime/meta built-ins

• SataAndagi() — runtime bootstrap/info map (truth)
• Americaya(x) — promote returned value to truth
• Getittogether() — stabilize unresolved grain state

Parser note: Getittogether is callable (Getittogether()), while Escalator / Elevator are declaration-style statements.

---

Architecture

Front-end

1. lexer.py tokenizes source.
2. parser.py builds AST (ast_nodes.py).

Interpreter path

• interpreter.py executes AST against runtime.py state.
• Tracks values, kinds, warnings/errors, traces, and buffered stdout/stderr.

Compiler + VM path

1. compiler.py lowers AST to bytecode (bytecode.py).
2. vm.py executes bytecode.
3. verifier.py checks stack effects, call arity, and block validity.

Equivalence path

• equiv_test.py runs both engines.
• equiv_lock.py compares traces and output for drift detection.

---

Testing and Validation

python3 run_tests.py
python3 run_tests.py --filter 06_sataandagi.saka
python3 -m unittest tests/test_verifier.py
python3 equiv_lock.py tests/equivalence/06_sataandagi.saka

---

Contributor Map

• lexer.py — lexer rules
• parser.py — parser + AST construction
• ast_nodes.py — AST node definitions
• interpreter.py — interpreter semantics
• compiler.py, bytecode.py, vm.py — compile + VM runtime
• verifier.py — verifier rules
• equiv_lock.py, equiv_test.py — equivalence tooling
• arg_parser.py, saka.py — CLI wiring

When changing language semantics:

1. Update interpreter behavior.
2. Mirror behavior in compiler/VM.
3. Update verifier rules if signatures/ops changed.
4. Update tests, especially in tests/equivalence/.
5. Re-run equivalence and verifier checks.

---

Packaging and Release

Metadata lives in pyproject.toml:

• package name: OsakaProgrammingLanguage
• console script: osaka = saka:main

Typical release flow:

rm -rf build dist *.egg-info
python3 -m pip install --upgrade build twine
python3 -m build
python3 -m twine check dist/*
python3 -m twine upload dist/*

License: MIT (LICENSE).