OsakaProgrammingLanguage 0.1.0

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

OsakaProgrammingLanguage (Osaka Lang)

Osaka Lang is a custom programming language implemented in Python, with:

• an AST interpreter
• a bytecode compiler + VM
• an Equivalence Lock to compare interpreter and VM behavior

You can run it from source (python3 saka.py) or as an installed CLI (osaka).

---

Quick Start

python3 saka.py examples/hello.saka
python3 saka.py --help

Main CLI flags

• --no-lock — disable equivalence lock
• --vm-only — execute only VM path
• --interpreter-only — execute only interpreter path
• --lock-strict — fail on lock mismatches
• --warnings-as-errors — treat warnings as errors in equivalence checks
• --debug — enable debug traces
• --show-lexer-tokens — print lexer token stream
• --repl — launch interactive Osaka REPL

Example:

python3 saka.py --show-lexer-tokens tests/equivalence/06_sataandagi.saka

Default mode now prints Say(...) program output directly. If a program emits no output, Osaka prints:

Tip: Use --debug for traces

---

Install CLI (osaka)

Install from local repo:

python3 -m pip install --upgrade "/Users/example/Desktop/Osaka Lang"

Or build a wheel:

cd "/Users/example/Desktop/Osaka Lang"
python3 -m pip wheel . --no-deps -w dist
python3 -m pip install --upgrade "dist/osakaprogramminglanguage-0.1.0-py3-none-any.whl"

Then:

osaka --help
osaka your_program.saka
osaka --repl

---

Language Guide

1) Declarations and kinds

Osaka Lang tracks value kinds:

• grainsoftruth → grain (uncertain)
• truthaboutgrain → truth (authoritative)

grainsoftruth g = 11;
truthaboutgrain t = Americaya(g);
Say(t);

2) Control flow

if and while require truthaboutgrain conditions at runtime.

truthaboutgrain ok = 1;
if (ok == 1) {
    Say("ready");
}

If a condition evaluates to grain, runtime raises an error (for example: while-condition must be truthaboutgrain).

3) Functions

Both function and func are accepted.

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

truthaboutgrain x = add(2, 3);
Say(x);

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

4) Collections

• Lists: [1, 2, 3]
• Maps: {"name": "SATA", "level": 6}
• Indexing: arr[i], m["key"]
• Index assignment: arr[i] = value;

truthaboutgrain nums = [1, 2];
push(nums, 3);
Say(nums);

truthaboutgrain profile = {"name": "SATA"};
Say(profile["name"]);

5) Mutation & governance built-ins

• Ah(x) — acknowledges variable for mutation
• youknowsealsright(x) — marks variable as assumed (suppresses mutation warning path)
• Ivebeengot(x) — legacy protection (blocks later mutation)
• Hecho(x) — freezes a variable when allowed

Typical behavior:

• mutating an initialized variable without Ah/assumption can warn
• mutating Hecho/Ivebeengot variables is blocked
• Hecho on grainsoftruth emits advisory info in current runtime behavior

6) Runtime/system built-ins

• Getittogether(); — stabilizes unresolved grain state
• SataAndagi() — returns runtime info map as truth
• Americaya(x) — promotes value to truth (returns promoted value)

grainsoftruth raw = 42;
Getittogether();
truthaboutgrain stable = Americaya(raw);
Say(stable);

7) Context progression statements

Parser accepts these as statement-style declarations:

Escalator reviewLevel2;
Elevator policyLevel;

Note: current parser rules treat Getittogether as a callable form with parentheses, while Escalator/Elevator are declaration-style statements.

---

Standard Library (currently implemented)

• Say(x)
• len(x)
• push(list, value)
• pop(list)
• contains(map, key)
• keys(map)
• values(map)
• slice(list_or_string, start, end)
• SataAndagi()
• Americaya(x)

---

Testing

Run a program through the main CLI:

python3 saka.py examples/hello.saka

Run direct interpreter-vs-VM equivalence harness:

python3 equiv_lock.py tests/equivalence/06_sataandagi.saka

Full test runner (project utility):

python3 run_tests.py

Single equivalence test:

python3 run_tests.py --filter 06_sataandagi.saka

Verifier unit tests:

python3 -m unittest tests/test_verifier.py

---

Implementation Map (contributors)

• lexer.py — tokenization / keywords
• parser.py — AST construction
• ast_nodes.py — AST node types
• interpreter.py — interpreter semantics
• compiler.py, bytecode.py, vm.py — compile + VM execution
• verifier.py — bytecode / signature checks
• equiv_lock.py, equiv_test.py — interpreter vs VM comparison
• arg_parser.py, saka.py — CLI

When changing language semantics:

1. Update interpreter behavior.
2. Mirror behavior in compiler/VM.
3. Update verifier rules if builtin signatures or op behavior changed.
4. Add/adjust tests (especially tests/equivalence/).
5. Re-check equivalence output before shipping.