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).

§4. Body operations

OpExampleCourt
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

OpFieldsNote
constvaluea literal
fieldnamedeclared in inputs / let / earlier assignment
arithleft, op, right+ - * / %; division/modulo by zero — refusal деление_на_ноль
compareleft, op, right== != < > <= >=; incomparable types — refusal типы_не_сошлись (types did not agree)
and / or / notleft, right / whatboolean, short-circuit
calldeal, argsa primitive or a deal of the file; the argument count is part of the contract
shelf-readaddressmissing / 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.

PrimitiveMeaning
rounded(x, digits)half-up; rounded(0.125, 2) = 0.13
hash(x)sha256 of the string representation
sum · length · max · minover lists and strings
join(list, separator)strings from elements
lower · log · timestrings, 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-indexbuilding 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

{"требует": {"оп": "и",
  "лево":  {"оп": "сравнение", "чем": ">=", "лево": {"оп": "поле", "имя": "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:

ClaimReality in v0.1.1
Stage 2 — completenessjudges name/inputs/body/witness; output/refusals are declared in the file, their enforcement is the next seam
Stage 3 — feasibilitystatic: calls exist, fields declared before use, stop names a declared refusal; no static type check — types are caught by witnesses (stage 4)
Stage 1 — forman 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 boundaryan 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 components8/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:

ErrorReproFix in v0.1.2
Mutable list literal leaks across callstwo cases [1,9] / [1,8] → [1,9,8]list/dict literals are deep-copied at execution
Rounding unsafe in floatrounded(1.005, 2) → 1.0Decimal 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 precision1e17+5 “equals” 1e17integers compare exactly (the float cast removed), fractional — 1e-9 tolerance (a named canon)
Input types not judgeda string under a declared number — greeninput types judged on every case; mismatch — canonical refusal
Shelf write escape../polka_evil/pwned.json createdclosed in v0.1.1 (the POLKA + os.sep boundary covers writes too) — re-verified
Codegen: name injection into exec (CWE-94)variable i' — SyntaxError escapedthe loop variable must be a canon identifier; a crooked one — canonical refusal
No step limita loop to 10^12 hung the compilerfuel: 10,000,000 steps — the canonical refusal «топливо» in ~5 s instead of forever; reset per case
Refusals not written to the registryreestr.jsonl unchanged after a refusala compiler refusal is written to the registry (tip: otkaz, stage, cause)
NaN accepted in ASTNaN serialized as invalid JSONNaN/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:

ErrorReproFix in v0.1.3
Diamond import falsely judged a cycleA→{B,C}, B→D, C→D — “duplicate” refusalcycles 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 escapedrounded(1e100, 2) — tracebackDecimal context with headroom + DecimalException in the primitive net — canonical refusal; 1e30 computes
Fuel bypassed in codegena 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+1mixed pairs compare exactly
Chronicle without a hash chain“cannot be shortened” — a convention onlyevery record carries pred + hesh_zapisi — shortening breaks the chain and is visible
Fixed .tmp — writers racetwo writes to one addresstmp is unique (pid+random), replace stays atomic
Registry grows without rotationa full AST on every green compilationa 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-codedfactorial(>300) uncomputablevm.ГЛУБИНА_ПОТОЛОК = 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

#TransformationCompiler court
1introduce-deal≥1 witness case, edges
2introduce-contract (auxiliary)the contract is full, no refused calls
3replace-bodyall witnesses executed, “ensures” on each
4add-witness-caseexecuted now; a missing edge is a claim
5remove-caseenough cases with edges remain
6narrow-requiresall callers re-checked
7widen-ensuresall witnesses re-driven
8add-refusalcallers’ bodies name the new refusal
9replace-callthe new contract by hash; types and refusals accounted
10rename-with-caller-carryevery caller carried over
11split-at-seamtwo deals equivalent to the sum
12merge-dealsthe merged one equals the sum
13introduce-typeapplied only by narrowing/widening
14mark-quarantinethe unverifiable lives only in a sandbox
15lift-to-primitivethe body becomes a VM call
16double-component-with-variationthe new component is independent

§10. Prohibitions of the language

  1. Free text in a body — only the canon operations.
  2. Side effects beyond the shelf boundary (network, processes, screen).
  3. Unbounded loops — the bound is part of the contract.
  4. Loose dependencies by paths/names — only hash addresses of contracts.
  5. Mutable global state — only the shelf.
  6. Two spellings of one construct — the compiler enforces the canon.
  7. 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.