Syntax and semantics
Everything below is the language canon, confirmed by a live compiler and the in-browser machine: the web interpreter at the bottom of this page executes the canon right here.
§1. The .deal file — canonical AST
The file stores a machine-readable AST in JSON — the single source of truth of a component. There is no “program text”: the projection is a computed view, printed from the AST. Canon rules: deterministic serialization order (two serial hashes of the same meaning must match byte-for-byte), one utf-8 encoding, one spelling of every construct (no aliases).
{"файл": "цена_за_единицу",
"сделки": [
{"имя": "деление",
"входы": [{"имя": "а", "тип": "число"}, {"имя": "б", "тип": "число"}],
"выход": "число",
"отказы": ["деление_на_ноль"],
"тело": [{"оп": "…", "…": "…"}],
"свидетель": [{"вход": {"а": 100000, "б": 4}, "выход": 25000.0},
{"вход": {"а": 100000, "б": 0}, "отказ": "деление_на_ноль"}]},
{"имя": "цена_за_единицу", "…": "…"}
]}
The canonical field names are Russian — the canon
fixes them, and the tables below give the English reading of every keyword and
field. A .deal file always uses these canonical spellings.
§2. Types
number (float), string, list,
dict, status (boolean), file (a shelf
address). No composite structures by design — complexity is assembled from deals.
§3. Contract and deal
A deal is the unit of a program: a contract header + body + witness. A contract without a body is an interface: it may be declared, not called (the compiler refuses).
requires— a precondition; a violation raises the canonical refusalнарушен_договор(contract violated), not a crash.ensures— a postcondition, executed on every witness case after the body (the result is fed into the expression asэто).refusals— a closed list of canonical refusal names; aстой(stop) in the body must name one of them or a canonical one.
§4. Body operations
| Op | Example | Court |
|---|---|---|
assign | {"name": "price", "what": {…}} | the expression is judged; the name becomes declared |
return | {"what": {…}} | returns the deal’s value |
stop (стой) | {"refusal": "name", "cause": "…"} | the refusal is named in the contract; it bubbles up the call stack to the witness expecting it |
append | {"name": "list", "what": {…}} | appends to a list; the first element creates it |
if / else | {"condition": {…}, "then": […], "else": […]} | both branches are statically judged |
for-until (для-каждого-до) | {"var": "i", "until": {…}, "body": […]} | a loop only with a bound in the contract; unbounded loops are impossible |
shelf-write | {"address": {…}, "value": {…}} | state lives only on the shelf, written atomically |
No pointers, no eval-like constructs, no free functions, no side effects beyond the shelf boundary.
§5. Expressions
| Op | Fields | Note |
|---|---|---|
const | value | a literal |
field | name | declared in inputs / let / earlier assignment |
arith | left, op, right | + - * / %; division/modulo by zero — refusal деление_на_ноль |
compare | left, op, right | == != < > <= >=; incomparable types — refusal типы_не_сошлись (types did not agree) |
and / or / not | left, right / what | boolean, short-circuit |
call | deal, args | a primitive or a deal of the file; the argument count is part of the contract |
shelf-read | address | missing / unparsable file — refusal полка_не_доступна (shelf unavailable) |
§6. Primitives — the frozen VM set
The AI never writes a primitive: they live in the VM and grow only through a
versioned decision. Note: rounded (округлено) uses
round-half-up (the mathematical rule), not banker’s rounding —
rounded(2.5, 0) = 3, rounded(0.125, 2) = 0.13.
| Primitive | Meaning |
|---|---|
rounded(x, digits) | half-up; rounded(0.125, 2) = 0.13 |
hash(x) | sha256 of the string representation |
sum · length · max · min | over lists and strings |
join(list, separator) | strings from elements |
lower · log · time | strings, math, Unix time |
element(list, index) | out of bounds — the canonical refusal за_краем, not an IndexError |
type-of(x) | the type’s name as a value |
list · dict · keys · field-or · dict-set · set-index | building and walking data |
shelf-read-or(address, default) | read with a default: missing file — the default, not a refusal |
A raw exception inside a primitive is translated into the canonical refusal
типы_не_сошлись with the primitive’s name and a fix hint — a primitive
never falls off a “Python stack”, it always answers in words.
§7. Witness — the proof of a deal
- At least 2 cases (deals with inputs — edges included); a deal with no inputs needs 1: the input space is empty, no edges exist.
- A case:
{"input": {…}, "output": …}or{"input": {…}, "refusal": "name"}; a property case{"property": {…}}— for values that cannot be pinned to a number. - Numbers compare with a 1e-9 tolerance (float comparison is not fragile).
- The
ensurespostcondition is checked on every case automatically — a double court: body and contract. - Hidden edges: for every numeric input the compiler substitutes
0 and 1,000,000 — the deal must answer with a canonical refusal or a sensible
number; an unpredictable crash paints the deal red. Bounds are fenced with
requires:
{"требует": {"оп": "и",
"лево": {"оп": "сравнение", "чем": ">=", "лево": {"оп": "поле", "имя": "n"},
"право": {"оп": "константа", "значение": 0}},
"право": {"оп": "сравнение", "чем": "<=", "лево": {"оп": "поле", "имя": "n"},
"право": {"оп": "константа", "значение": 100000}}}}
A live lesson: the “factorial” deal without a fence
honestly churned a million interpreter iterations on the hidden edge n=1,000,000 —
a requires cut the edge canonically and compilation returned to a
fraction of a second. Fencing edges is not decoration; it is part of the proof.
Witness limits — stated honestly: a witness proves “agreed / disagreed” on the named and hidden cases — it proves the presence of an error, not its absence. Witness quality is part of the proof: weak cases judge weakly (the same AI submits the witnesses — a named boundary of the language, not a secret). Canon mitigations: hidden edges 0 and 1,000,000, edge cases, property cases, “ensures” on every case.
§8.1. The v0.1.1 implementation — what is judged today, what is the next seam
An external audit (an independent AI, 2026-11-20) checked the description against the package code. The honest summary:
| Claim | Reality in v0.1.1 |
|---|---|
| Stage 2 — completeness | judges name/inputs/body/witness; output/refusals are declared in the file, their enforcement is the next seam |
| Stage 3 — feasibility | static: calls exist, fields declared before use, stop names a declared refusal; no static type check — types are caught by witnesses (stage 4) |
| Stage 1 — form | an unknown operation falls at stage 3/4 with a name; a dedicated form check is the next seam |
| “Refusals are always verbal” | the compiler refusal prints as JSON: {stage, culprit, cause, what_to_fix}; no tracebacks |
| Shelf boundary | an address cannot leave the shelf folder (compared against POLKA + os.sep); the escape into a neighbour folder is closed (verified by a ../polka_* probe) |
| Eight green components | 8/8 in the package, shelf fixtures included; projection bijectivity confirmed by the external audit independently |
§8.2. The second audit round — what v0.1.2 fixes
The same external AI went deeper: money semantics, types, sandbox, codegen, determinism. Every point is closed in v0.1.2 and verified by a probe on the repro:
| Error | Repro | Fix in v0.1.2 |
|---|---|---|
| Mutable list literal leaks across calls | two cases [1,9] / [1,8] → [1,9,8] | list/dict literals are deep-copied at execution |
| Rounding unsafe in float | rounded(1.005, 2) → 1.0 | Decimal from the string representation, ROUND_HALF_UP: 1.005 → 1.01; 2.5 → 3; 0.125 → 0.13 — the half-up canon preserved |
| Witness comparison loses precision | 1e17+5 “equals” 1e17 | integers compare exactly (the float cast removed), fractional — 1e-9 tolerance (a named canon) |
| Input types not judged | a string under a declared number — green | input types judged on every case; mismatch — canonical refusal |
| Shelf write escape | ../polka_evil/pwned.json created | closed in v0.1.1 (the POLKA + os.sep boundary covers writes too) — re-verified |
| Codegen: name injection into exec (CWE-94) | variable i' — SyntaxError escaped | the loop variable must be a canon identifier; a crooked one — canonical refusal |
| No step limit | a loop to 10^12 hung the compiler | fuel: 10,000,000 steps — the canonical refusal «топливо» in ~5 s instead of forever; reset per case |
| Refusals not written to the registry | reestr.jsonl unchanged after a refusal | a compiler refusal is written to the registry (tip: otkaz, stage, cause) |
| NaN accepted in AST | NaN serialized as invalid JSON | NaN/Infinity forbidden at load and serialization (allow_nan=False) |
An honestly named remainder: the 1e-9 tolerance for fractional values is canon (money: cents), 1e-10 noise inside it passes; static type checking (stage 3) is the next seam of the language, under construction. Benchmark methodology and the native backend are outside the package (pilot figures, labelled).
§8.3. Third audit round — v0.1.3
Deeper: composition, money, integrity, backend equivalence. All closed in v0.1.3, verified by probes on the repros:
| Error | Repro | Fix in v0.1.3 |
|---|---|---|
| Diamond import falsely judged a cycle | A→{B,C}, B→D, C→D — “duplicate” refusal | cycles judged ALONG THE PATH (stack), same-HASH import deduplicated; an import brings its transitive environment (live find: calls inside the imported file fell with нет_договора) |
| Raw decimal.InvalidOperation escaped | rounded(1e100, 2) — traceback | Decimal context with headroom + DecimalException in the primitive net — canonical refusal; 1e30 computes |
| Fuel bypassed in codegen | a 1e9 loop hung codegen | _sf() in every generated loop turn — canonical refusal «топливо» in ~2 s |
| int↔float compare hid precision loss | (1e16+1)/1 → float 1e16 “equals” int 1e16+1 | mixed pairs compare exactly |
| Chronicle without a hash chain | “cannot be shortened” — a convention only | every record carries pred + hesh_zapisi — shortening breaks the chain and is visible |
| Fixed .tmp — writers race | two writes to one address | tmp is unique (pid+random), replace stays atomic |
| Registry grows without rotation | a full AST on every green compilation | a hash repeat — a light record (tip: povtor, no AST) |
| Typo тии_не_сошлись in the protocol | — | типы |
| string×number allowed | "ab"*3 → "ababab" | arithmetic is strict: strings are joined by the join primitive |
| Depth 300 hard-coded | factorial(>300) uncomputable | vm.ГЛУБИНА_ПОТОЛОК = N — configurable |
The differential backend probe (the audit’s suggestion — accepted): 300 random expressions on the interpreter and the bytecode — 300/300 agreed, zero divergences. Honestly remaining: static type court (stage 3), the 1e-9 fractional tolerance (money canon), the native backend and benchmark methodology — outside the package.
§8. Refusals — always verbal
The canonical VM refusal names: деление_на_ноль (division by zero),
нарушен_договор (contract violated), полка_не_доступна
(shelf unavailable), нет_договора (no such deal), нет_имени
(no such name), нет_операции (no such operation),
полка_наружу (shelf escape), типы_не_сошлись (types did
not agree), за_краем (out of bounds), глубина (depth),
топливо (fuel — v0.1.2: the computation spent 10,000,000 body steps,
instead of an endless loop). A refusal bubbles up the call stack to the witness expecting it — or to the top of
the computation. There is no catch construct by design: a refusal is always named
and always arrives.
A compiler refusal has four fields:
{"stage": 3, "culprit": "call деление_не_то",
"cause": "the deal is not among the imports; деление is available (hash a1b2c3)",
"what_to_fix": "replace the call with деление or add the hash import"}
§9. Sixteen transformations — the whole way an AI works
| # | Transformation | Compiler court |
|---|---|---|
| 1 | introduce-deal | ≥1 witness case, edges |
| 2 | introduce-contract (auxiliary) | the contract is full, no refused calls |
| 3 | replace-body | all witnesses executed, “ensures” on each |
| 4 | add-witness-case | executed now; a missing edge is a claim |
| 5 | remove-case | enough cases with edges remain |
| 6 | narrow-requires | all callers re-checked |
| 7 | widen-ensures | all witnesses re-driven |
| 8 | add-refusal | callers’ bodies name the new refusal |
| 9 | replace-call | the new contract by hash; types and refusals accounted |
| 10 | rename-with-caller-carry | every caller carried over |
| 11 | split-at-seam | two deals equivalent to the sum |
| 12 | merge-deals | the merged one equals the sum |
| 13 | introduce-type | applied only by narrowing/widening |
| 14 | mark-quarantine | the unverifiable lives only in a sandbox |
| 15 | lift-to-primitive | the body becomes a VM call |
| 16 | double-component-with-variation | the new component is independent |
§10. Prohibitions of the language
- Free text in a body — only the canon operations.
- Side effects beyond the shelf boundary (network, processes, screen).
- Unbounded loops — the bound is part of the contract.
- Loose dependencies by paths/names — only hash addresses of contracts.
- Mutable global state — only the shelf.
- Two spellings of one construct — the compiler enforces the canon.
- Secrets inside a component’s body.
§11. Web interpreter
The canon executes right in the browser — the same semantics as the Python VM: the same canonical refusals, the same rounding, the same call depth and witness court.