Kaze, in detail.
Everything in the current standalone language surface, from your first expression to the boundaries around a host call.
This reference describes the separate standalone Kaze 1.0 source, snapshot 10 November 2026. Sofuu embeds a different Kaze 0.1 engine with different features and bytecode; these examples are not a guarantee for sofuu script or published binaries.
Examples in individual entries can be fragments; place them inside a routine and supply the stated declarations, grants, and policy where required.
373 reference entries · Search by name, status, or behavior
Every inventory row has at least one status tag. Tags describe this snapshot; IMPLEMENTED alone is a source-code observation, not proof of deployment.
| Tag | Meaning |
|---|---|
| implemented | Present in the inspected standalone source for the stated scope. |
| verified | Additionally checked locally; the evidence section identifies pure checks, real local operations, or explicitly labelled robotics simulation. |
| partial | Present with a stated gap, restriction, or incomplete enforcement. |
| live path | A real hardware code path exists; a configured device and appropriate permissions are still required. |
| unverified | This inventory did not verify the stated physical device, external integration, or published artifact. |
| simulated | The built-in path supplies simulated state or an imitation rather than a real external operation. |
| registry only | The name and arity are recognized, but the inspected built-in host has no matching implementation. |
| post baseline | This detail differs from the frozen standalone v1.0 baseline; the release compatibility decision remains open. |
| unsupported | No corresponding general feature is implemented in this standalone surface. |
| target | A repository requirement or intended behavior, not a verified implementation. |
Policy note: RULES.md §1.9 permits explicitly selected and labelled robotics/drone simulation for testing. In this source snapshot the standalone host refuses unavailable non-robotics backends instead of simulating them. Simulator selection is explicit and reported; physical hardware has not been verified.
A small program
Pure computation · no capabilities required
action main(amount):
let total = 0
for each value in [1, 2, 3]:
set total to total + value
return total + amountkaze run example.kaze --arg amount=4 --plain
# main -> 101.1 Source structure and lexical rules
| Item | Tag | Exact form and behavior |
|---|---|---|
File encodingExamplekaze check - < example.kaze | implemented | UTF-8 source. kaze run - and kaze check - read source from stdin. |
ProgramExampleaction main():
return 1 | implemented | Optional headers followed by at least one action, check, filter, when, or every item. A header-only file is rejected. |
Header orderExampleneeds: log
use "helpers.kaze" | implemented | needs: and use lines can appear in either order before the first item. Each file permits at most one needs: line. |
BlockExampleaction main():
return 1 | implemented verified | A colon ends the header; the body starts on the next line with at least one indented statement. Dedents must match a previous indentation level. |
IndentationExample return 1 | implemented | Spaces are used; the formatter uses four spaces per level. Tabs in code outside strings/comments are rejected. |
CommentsExample# This is a comment | implemented | # outside a string starts a comment through the end of the line. |
ContinuationExample[1,
2] | implemented | Newlines inside (...) or [...] continue the expression. |
IdentifierExampletotal_count | implemented | ASCII [A-Za-z_][A-Za-z0-9_]*; names are case-sensitive. |
Text literalExample"hello\nworld" | implemented | Double-quoted, single-line text. Supported escapes: \n, \t, \", \\. |
Number literalExample1.25 | implemented | Decimal integer or fraction such as 12 or 1.25; the literal must fit a finite f64. Leading - is an operator. Exponents and hexadecimal are not numeric literals. |
| Punctuation | implemented | :, (, ), ,, ., %, +, -, *, /, <, >, =, [, ]; plus <=, >=, ==, !=. |
| Semicolon and braces | unsupported | No general semicolon statement separator, {...} block, or map literal syntax. |
1.2 Header and declaration syntax
| Syntax | Tag | Meaning and constraints |
|---|---|---|
needs: family, familyExampleneeds: drone, log | implemented | Declare capability resources. Duplicate names in one header are rejected. A declaration is not itself a backend grant. |
use "path.kaze"Exampleuse "helpers.kaze" | implemented verified | Compile-time include. The path must end in .kaze; relative paths resolve from the importing file. |
action name(a, b):Exampleaction main(amount): | implemented | Declare an executable named routine with positional signature names. |
check name(a, b):Examplecheck valid(value): | implemented | Declare a named check routine. Runtime entry binding works like an action. |
filter name(a, b):Examplefilter gate(text): | partial verified | Declare a policy-oriented routine; the checker allows a plain return, which can yield no verdict. |
when condition:Examplewhen 1 == 1: | implemented | Declare a hook evaluated on each requested supervisor tick. |
every 100 ms:Exampleevery 100 ms: | implemented | Declare a periodic hook with a numeric literal and time unit. It runs on ticks whose virtual time is divisible by its period. A zero period is never due. |
| Duplicate routine names | implemented | Rejected within one file and on module merge. Hook names are generated. |
| Parameter defaults / annotations | unsupported | Routine signatures contain names only; no default values or source type annotations. |
1.3 Statements
| Syntax | Tag | Meaning |
|---|---|---|
let name = expressionExamplelet count = 1 | implemented verified | Bind a value in the current scope. |
set name = expressionExampleset count = 2 | implemented | Reassign an existing binding. |
set name to expressionExampleset count to 2 | implemented verified | Alternative spelling for set. |
if condition:Exampleif count > 0: | implemented | Run its indented block when the condition is true. |
otherwise: after ifExampleif count > 0:
return count
otherwise:
return 0 | implemented | Optional alternative block. |
for each item in values:Examplefor each item in [1, 2, 3]: | implemented verified | Iterate over a list; the loop variable is local to its body. |
while condition:Examplewhile count < 3: | implemented | Repeat while the condition is true, subject to the run's fuel and applicable deadline. |
try:Exampletry:
arm drone
otherwise with error:
return error.code | implemented | Start a protected block for the specific recoverable host errors in §5. |
otherwise: after tryExampletry:
arm drone
otherwise:
return 0 | implemented | Required recovery block; it can omit an error binding. |
otherwise with error:Exampleotherwise with error:
return error.code | implemented | Recovery block with error.code, error.message, and error.line. |
returnExamplereturn | implemented | End the current item with the runtime value nothing. |
return expressionExamplereturn count | implemented verified | End the current item with that value. |
return to launchExamplereturn to launch | implemented | Capability sentence for drone.rtl(); this is a host operation, not the ordinary return statement. |
Expression statementExamplesin(0) | implemented | Evaluate an expression and discard its value unless it is a policy verdict. |
break / continue | unsupported | No general loop-control statements. |
| Field or index assignment | unsupported | set record.field ... and set list[index] ... are not general assignment forms. |
1.4 Expressions and operators
| Form | Tag | Meaning and restrictions |
|---|---|---|
nameExamplecount | implemented | Read a parameter or local binding; some unbound names can resolve as bare telemetry. |
(expression)Example(2 + 3) * 4 | implemented | Group an expression. |
[a, b, ...]Example[1, 2, 3] | implemented | Ordered list literal; at most 255 elements per literal. |
value[index]Examplevalues[0] | implemented | Zero-based read from a list, text, or point; index must be a nonnegative integer in range. |
name.fieldExamplepoint.z | implemented | Read a field from a named record or point. A missing record field returns nothing. |
receiver.operation(args)Exampledrone.telemetry("battery") | partial | Call a registered capability operation. The receiver is a resource/family name, not a general object method. At the beginning of a statement, log.info(...) is parsed as the log sentence and fails; use log value or place the call in an expression. |
log.info(...) as a statementExamplereturn log.info("ready") | partial verified | Rejected by the current parser because log starts a sentence. return log.info(...) passes the front end; log value is the usual sentence form. Other log.<level>(...) statements encounter the same dispatch. |
length of valueExamplelength of "hello" | implemented | Character count for text, element count for lists, and Euclidean magnitude for a point. |
-valueExample-3 | implemented | Numeric negation; point negation is supported. |
not valueExamplenot false | implemented | Boolean negation; the checker expects boolean where it knows the type. |
a + bExample2 + 3 | implemented | Add numbers or points, or concatenate two text values. |
a - bExample5 - 2 | implemented | Subtract numbers or points. |
a * bExample2 * 3 | implemented | Multiply numbers or scale a point by a number. |
a / bExample6 / 2 | implemented | Divide numbers or divide a point by a number; zero divisor raises E_KAZE_DIV0. |
a % bExample(5) % 2 | partial verified | Numeric remainder. Immediately after a numeric literal % can instead be consumed as a percent unit: return 5 % 2 returned 5 in a local probe. Use return (5) % 2 or a variable for the left operand. |
a < b, a <= bExample1 < 2 | implemented | Ordering comparisons for compatible numbers or text. |
a > b, a >= bExample3 >= 2 | implemented | Ordering comparisons for compatible numbers or text. |
a == b, a != bExample2 == 2 | implemented | Equality / inequality. Points compare components; lists and records compare their heap identities, not deep structural contents. |
a and bExampletrue and false | implemented | Short-circuit conjunction; the right side is skipped if the left is false. |
a or bExampletrue or false | implemented | Short-circuit disjunction; the right side is skipped if the left is true. |
routine(args) | unsupported | No direct call from one user-defined Kaze routine to another. Use --entry to select a routine. |
| Chained comparisons | unsupported | The grammar handles one comparison at a time; do not rely on a < b < c. |
| String interpolation | unsupported | Build supported text using literals and + between text values. |
Operator precedence, from tighter to looser: postfix/indexing and angle conversion; unary -; * / %; + -; comparison; not; and; or. Use parentheses when the intended grouping is not obvious.
1.5 Mathematical and spatial forms
| Syntax | Tag | Result and constraints |
|---|---|---|
vector(x, y)Examplevector(1, 2) | implemented | Create a point with z = 0. |
vector(x, y, z)Examplevector(1, 2, 3) | implemented verified | Create a point from three numeric components. |
distance between a and bExampledistance between vector(0, 0) and vector(1, 1) | implemented | Great-circle ground distance in meters; a and b are geographic points. |
slant distance between a and bExampleslant distance between vector(0, 0, 0) and vector(1, 1, 5) | implemented | Ground distance combined with altitude difference. |
bearing of offsetExamplebearing of vector(1, 2) | implemented | Compass bearing of a local vector in degrees: north 0, east 90. |
bearing from a to bExamplebearing from vector(0, 0) to vector(1, 1) | implemented | Initial compass bearing between two geographic points. |
bearing to targetExamplebearing to vector(1, 1) | partial | Uses ambient latitude/longitude from exactly one declared hardware resource in the file; backend availability controls whether the position is real. |
sin(x)Examplesin(30 in radians) | implemented | Sine of a number in radians. |
cos(x)Examplecos(0) | implemented | Cosine of a number in radians. |
atan2(y, x)Exampleatan2(1, 1) | implemented | Two-argument arctangent; result is radians. |
sqrt(x)Examplesqrt(9) | implemented verified | Square root; a negative input raises E_KAZE_MATH. |
x in radiansExample180 in radians | implemented | Convert degrees to radians. |
x in degreesExample3.141592653589793 in degrees | implemented | Convert radians to degrees. |
link lost for 3 secondsExamplelink lost for 3 seconds | partial | Boolean link-silence expression; requires a drone declaration, grant, valid policy, and configured backend. Window must be 1 through 4,294,967,295 ms. A real result requires a live link. |
policy detects kind in textExamplepolicy detects secrets in "sample" | partial | Lowers to policy.detects(kind, text); detector behavior depends on the host. |
recall memories matching queryExamplerecall memories matching "greeting" | registry only | Lowers to memory.recall(query); the standalone built-in host currently refuses it with E_CAP_MISSING. |
1.6 Sentence-form capability calls
These forms are syntactic sugar. Their tags describe parsing; §4 gives the separate real-backend status and required declaration/grant.
| Sentence | Tag | Lowers to |
|---|---|---|
log valueExamplelog "ready" | implemented | log.info(value). |
log info valueExamplelog info "ready" | implemented | log.info(value). |
log warn value / log warning valueExamplelog warning "check" | implemented | log.warn(value). |
log error valueExamplelog error "failed" | implemented | log.error(value). |
log debug valueExamplelog debug "detail" | implemented | log.debug(value). |
send alert valueExamplesend alert "ready" | implemented | alert.send(value). |
remember value as labelExampleremember "hello" as "greeting" | implemented | memory.save(label, value). |
recall memories matching queryExamplerecall memories matching "greeting" | implemented | memory.recall(query). |
allow / allow valueExampleallow "accepted" | implemented | policy.allow() / policy.allow(value) and terminate the item. |
reject with reasonExamplereject with "too long" | implemented | policy.reject(reason) and terminate the item. |
arm droneExamplearm drone | implemented | drone.arm(); the noun resolves to its family. |
takeoff to heightExampletakeoff to 10 meters | implemented | drone.takeoff(height). |
fly to pointExamplefly to vector(47.6, 8.5, 15) | implemented | drone.goto(point). |
fly to point at altitudeExamplefly to vector(47.6, 8.5, 0) at 15 meters | implemented | drone.goto(point, altitude). |
land / land droneExampleland drone | implemented | drone.land(). |
hold / hold positionExamplehold position | implemented | drone.hold(). |
return to launchExamplereturn to launch | implemented | drone.rtl(). |
stop drone / stop roverExamplestop rover | implemented | <family>.stop(). |
drive / drive forwardExampledrive forward at 1 m/s | implemented | rover.forward(); at speed supplies a speed. |
drive backwardExampledrive backward at 1 m/s | implemented | rover.backward(); at speed supplies a speed. |
turn left by degreesExampleturn left by 90 degrees | implemented | rover.turn_left(degrees). |
turn right by degreesExampleturn right by 90 degrees | implemented | rover.turn_right(degrees). |
turn on nameExampleturn on fan | implemented | device.set_relay("name", true). |
turn off nameExampleturn off fan | implemented | device.set_relay("name", false). |
pulse name for durationExamplepulse fan for 2 seconds | implemented | device.pulse("name", duration). |
Lists, points, and a record
Records can enter as JSON arguments; record literals are not supported.
action main(item):
let values = [2, 4, 6]
let point = vector(1, 2, 3)
return item.count + values[0] + point.zkaze run values.kaze --arg 'item={"count":5}' --plain
# main -> 102.1 Runtime values
| Value | Tag | Creation, access, and behavior |
|---|---|---|
NumberExample12 · 3.5 | implemented | Finite f64; for example 12, 3.5, or a numeric --arg. Arithmetic can raise overflow or division errors. |
TextExample"hello" | implemented | UTF-8, for example "hello"; text concatenation uses +. Indexing and length use Unicode scalar values, not bytes or grapheme clusters. |
BooleanExampletrue · false | implemented | Source literals true and false. |
ListExample[1, "a", true] | implemented | [1, "a", true] or a JSON array argument; ordered, zero-based, and heap-backed. |
Record/mapExample--arg 'item={"count":5}' | partial | A JSON object argument or host can supply a record. Read name.field; no record literal or field assignment. |
Point/vectorExamplevector(1, 2, 3) | implemented | vector(x, y) or vector(x, y, z). Read indexes 0, 1, 2 or named components below. |
Nothing/unitExamplereturn | implemented | Runtime value from an empty return, a missing field, JSON null, or a missing parameter. No general nothing source literal. |
Error recordExampleotherwise with err: … err.code | implemented | In a recovery block, .code and .message are text and .line is a number. |
| Point component | Tag | Equivalent names |
|---|---|---|
First componentExamplepoint.x | implemented | .x, .lat, .latitude, or [0]. |
Second componentExamplepoint.y | implemented | .y, .lon, .longitude, or [1]. |
Third componentExamplepoint.z | implemented | .z, .alt, .altitude, or [2]. |
| Geographic place | implemented | Spatial distance/bearing checks latitude -90..90 and longitude -180..180; invalid places raise E_KAZE_RANGE. |
2.2 Numeric literal units
| Unit | Tag | Accepted suffixes | Representation |
|---|---|---|---|
DistanceExample10 meters | implemented | m, meter, meters | Numeric value in meters. |
SpeedExample1 m/s | implemented | m/s | Numeric value in meters per second. |
AngleExample90 degrees | implemented | deg, degree, degrees | Numeric value in degrees. |
TimeExample3 seconds | implemented | s, sec, second, seconds | Numeric value in seconds. |
MillisecondsExample500 ms | implemented | ms, millisecond, milliseconds | Normalized to seconds: 500 ms becomes 0.5. |
PercentageExample20% | implemented | %, percent | Whole-number convention: 20% is 20, not 0.2. |
| Dimensional mismatch checking | partial verified | Any unit combination | The current checker accepts 1 meters < 1 seconds; units are not retained as runtime tags. Do not assume dimensional safety. |
| Arbitrary/user-defined units | unsupported | — | No general unit declaration or conversion system. |
An entry and a periodic hook
Hooks run only when ticks are requested. Logging requires a grant and valid policy.
needs: log
action main():
log "starting"
every 100 ms:
log "tick"kaze run routine.kaze --cap log --ticks 2 --tick-ms 100| Item | Tag | Behavior |
|---|---|---|
ActionExampleaction main():
return 1 | implemented | A named action may return a value or nothing. |
CheckExamplecheck valid(value):
return value > 0 | implemented | A named check is selected and bound like an action; it has no separate mandatory boolean-return rule. |
FilterExamplefilter gate(text):
allow text | partial verified | Intended to stop at allow or reject. A plain return also passes the current checker and can yield a null verdict. |
Explicit entryExample--entry main | implemented verified | --entry name selects a named item, including an imported item. Missing names give E_KAZE_ENTRY. |
Root main | implemented | Without --entry, a main from the root file is preferred. |
| Single root routine | implemented | Without root main, the sole root action/check/filter is selected. |
| Multiple root routines | implemented | Without an explicit entry or root main, ambiguous selection raises E_KAZE_ENTRY. |
| Hooks-only root | implemented | Can run with no entry; hooks require ticks to execute. |
| Imported implicit entry | unsupported | Imported routines do not become the implicit root entry. |
ParametersExample--arg amount=4 | partial | Bound by name or numeric key in --arg. Missing values become nothing instead of an early missing-parameter diagnostic. |
when hookExamplewhen 1 == 1: | implemented | Predicate runs for each requested tick; body runs when true. |
every hookExampleevery 100 ms: | implemented | Runs when period divides virtual tick time. Time begins at 0, so a positive period is initially due. |
| Tick pacing | implemented | --pace sleeps between ticks; without it scheduling advances virtual time without a sleep. |
| Hook state | partial | VM locals/stack are recreated for each item; arena and heap are cleared after each tick. Host state can remain separate. |
| Routine calls | unsupported | A routine cannot directly invoke another routine using ordinary call syntax. |
| Runtime imports / namespaces | unsupported | use is an include at compilation, with a shared global item namespace. |
| Import cycle / collision | implemented | Cycles and duplicate item names fail. Shared dependencies are included once. |
Example: pure action
action main(amount):
let total = 0
for each value in [1, 2, 3]:
set total to total + value
return total + amountkaze run example.kaze --arg amount=4 --plain returns 10.
Example: filter and error recovery
needs: policy
filter limit_length(text):
if length of text > 120:
reject with "too long"
otherwise:
allow textneeds: drone
action recover():
try:
arm drone
otherwise with problem:
return problem.code
when link lost for 3 seconds:
return to launchThe examples were checked without executing their capabilities. Actual drone operations need an authorized, configured backend.
Explicit drone simulation
Testing only · this is simulated, not a physical flight. A valid policy.json is required.
needs: drone
action main():
arm drone
takeoff to 10 meters
return to launchkaze run simulation.kaze --cap drone=sim --plain4.1 Gate and backend tags
Every operation below requires a matching needs: declaration, an explicit host grant, and a valid policy. Selected physical arguments are checked before dispatch. An operation's tag describes the built-in standalone host, not every possible custom CapHost supplied by an embedding application.
| Gate | Tag | Current behavior |
|---|---|---|
| H-1: declaration | implemented | An undeclared family is rejected; the checker can reject it before execution. |
| H-2: grant | implemented post baseline verified | Requires an explicit host grant for every capability family. |
| H-3: policy | implemented post baseline verified | Missing, malformed, unsupported, or denying policy causes E_CAP_DENIED. --no-policy does not bypass this gate. |
| H-4: arguments | partial | Selected physical arguments have type/range checks and are rejected rather than clamped; coverage is not universal. |
| Default host | implemented post baseline | No physical or simulated backend is selected implicitly. Missing backends return E_CAP_MISSING. |
| Simulator selection | implemented post baseline verified | drone=sim and rover=sim must be selected explicitly for testing; run reports identify selected simulators. |
| Live host fallback | implemented post baseline verified | Unconfigured sensor, device, alert, memory, AI, and tool operations return unavailable errors rather than simulated success. |
| Link-loss gate | implemented post baseline verified | Link monitoring checks the drone declaration, grant, policy, and backend before reading the host. |
| Lazy live link | implemented post baseline verified | The live drone connection opens only after the relevant VM gate approves the operation. |
| Live telemetry freshness | partial target | The live link uses a two-second timeout on received bytes, not a 1.5-second heartbeat and per-field telemetry freshness veto. Partial targets can use a previously reported value whose age is unknown. The RULES.md safety requirement is not yet met. |
| Live drone actuation | post baseline verified unsupported | The built-in host returns E_CAP_DENIED for live actuation before opening the link until the required freshness checks are implemented. Explicit drone simulation remains available for testing. |
| Physical hardware execution | unverified | The source has MAVLink and Linux GPIO/PWM paths; this inventory did not run a vehicle or device. |
4.2 Drone operations
These require needs: drone, a drone grant and a valid policy. MAVLink actuation code exists but is disabled by the built-in host until freshness checks are implemented. The explicitly selected simulator is for testing only; the live path was not physically verified here.
| Operation | Tag | Arguments and behavior |
|---|---|---|
drone.arm()Examplearm drone | live path unverified | No arguments; request arming and wait for armed telemetry on the live path. |
drone.takeoff(height)Exampletakeoff to 10 meters | live path unverified | One number in meters; gate checks 0..500. |
drone.goto(target)Examplefly to vector(47.6, 8.5, 15) | live path unverified partial | One point or numeric latitude. The currently disabled partial live-target code requires previously reported telemetry rather than fabricated coordinates or altitude; freshness is not checked. |
drone.goto(target, altitude)Examplefly to vector(47.6, 8.5, 0) at 15 meters | live path unverified | Two arguments; supported point/altitude or numeric forms have backend-specific interpretation. |
drone.goto(lat, lon, altitude)Exampledrone.goto(47.6, 8.5, 15) | live path unverified | Three numeric arguments; latitude is checked -90..90, longitude -180..180, and altitude 0..500 meters. |
drone.land()Exampleland drone | live path unverified | No arguments; request landing. |
drone.rtl()Examplereturn to launch | live path unverified | No arguments; request return to launch. |
drone.hold()Examplehold position | live path unverified | No arguments; request hold/loiter. |
drone.stop()Examplestop drone | live path unverified | No arguments; live path maps to hold/loiter. |
drone.telemetry(field)Exampledrone.telemetry("battery") | live path unverified | One field name; live telemetry can report a link error if no reading arrives. |
4.3 Rover and sensor operations
These require a family declaration and grant. Rover simulation requires an explicit testing selection; no built-in live rover or sensor backend has been established. Sensor calls now fail rather than return simulated readings.
| Operation | Tag | Arguments and behavior |
|---|---|---|
rover.forward()Exampledrive forward | simulated | No speed argument; simulator uses its own default. |
rover.forward(speed)Exampledrive forward at 1.2 m/s | simulated | One speed; supplied value is checked 0..10 m/s. |
rover.backward()Exampledrive backward | simulated | No speed argument; simulator uses its own default. |
rover.backward(speed)Exampledrive backward at 1 m/s | simulated | One speed; supplied value is checked 0..10 m/s. |
rover.turn_left(angle)Exampleturn left by 90 degrees | simulated | One angle in degrees. |
rover.turn_right(angle)Exampleturn right by 90 degrees | simulated | One angle in degrees. |
rover.stop()Examplestop rover | simulated | No arguments. |
rover.telemetry(field)Examplerover.telemetry("speed") | simulated | One field name. |
sensor.temperature()Examplesensor.temperature() | registry only | No arguments; built-in host returns E_CAP_MISSING. |
sensor.humidity()Examplesensor.humidity() | registry only | No arguments; built-in host returns E_CAP_MISSING. |
sensor.distance()Examplesensor.distance() | registry only | No arguments; built-in host returns E_CAP_MISSING. |
sensor.front_distance()Examplelidar.front_distance() | registry only | No arguments; built-in host returns E_CAP_MISSING. |
sensor.read(name)Examplesensor.read("ambient") | registry only | One name or pin; built-in host returns E_CAP_MISSING. |
sensor.telemetry(field)Examplesensor.telemetry("temperature") | registry only | One field name; built-in host returns E_CAP_MISSING. |
4.4 Device operations
These require needs: device or a device alias and a device grant.
| Operation | Tag | Arguments and behavior |
|---|---|---|
device.set_relay(name, on)Exampleturn on fan | live path unverified | Name and boolean or finite numeric state; live Linux GPIO requires a named pin. |
device.pulse(name, seconds)Examplepulse fan for 2 seconds | live path unverified | Name and duration; gate checks 0..60 seconds. |
device.read_gpio(name)Exampledevice.read_gpio("fan") | live path partial unverified | One name; live path returns a boolean, while the checker currently infers a number. The mismatch can reject an if condition. |
device.set_duty(name, percent)Exampledevice.set_duty("fan", 60) | live path unverified | Name and PWM percentage; gate checks 0..100. A named PWM channel is required for the live PWM path. |
| Missing device mapping | implemented post baseline | Without a suitable live GPIO/PWM mapping, device operations return E_CAP_MISSING. |
4.5 Memory, policy, logging, alerts, AI, and tools
| Operation | Tag | Arguments and current behavior |
|---|---|---|
memory.save(label, value)Exampleremember "hello" as "greeting" | registry only | Two arguments; the standalone built-in host returns E_CAP_MISSING. |
memory.recall(query)Examplerecall memories matching "greeting" | registry only | One argument; the standalone built-in host returns E_CAP_MISSING. |
policy.detects(kind, text)Examplepolicy detects secrets in "sample" | partial | Two arguments; the built-in host uses a small local pattern detector for secrets and prompt_injection; unknown kinds return E_CAP_MISSING. |
policy.detect(kind, text)Examplepolicy.detect("secrets", "sample") | partial | Alias operation with the same built-in detection behavior. |
policy.allow()Exampleallow | implemented | VM records an allow verdict with nothing. |
policy.allow(value)Exampleallow "accepted" | implemented | VM records an allow verdict with the rendered value. |
policy.reject(reason)Examplereject with "too long" | implemented | VM records a reject verdict with the reason. |
log.info(value)Examplelog "started" | implemented | One argument; captured in the run report's logs. |
log.warn(value)Examplelog warning "check" | implemented | One argument; captured at warning level. |
log.error(value)Examplelog error "failed" | implemented | One argument; captured at error level. |
log.debug(value)Examplelog debug "detail" | implemented | One argument; captured at debug level. |
alert.send(text)Examplesend alert "ready" | registry only | One argument; the built-in host returns E_CAP_MISSING instead of pretending to deliver. |
ai.prompt(text)Exampleai.prompt("summarize") | post baseline registry only | One argument is recognized in this source snapshot; no built-in inference handler. |
ai.complete(text)Exampleai.complete("summarize") | post baseline registry only | One argument is recognized in this source snapshot; no built-in inference handler. |
ai.classify(text, classes)Exampleai.classify("hello", ["greeting", "other"]) | post baseline registry only | Two arguments are recognized in this source snapshot; no built-in classifier handler. |
tool.call(name)Exampletool.call("lookup") | post baseline registry only | One argument is recognized in this source snapshot; no built-in tool handler. |
tool.call(name, input)Exampletool.call("lookup", "term") | post baseline registry only | Two arguments are recognized in this source snapshot; no built-in tool handler. |
tool.run(name)Exampletool.run("lookup") | post baseline registry only | One argument is recognized in this source snapshot; no built-in tool handler. |
tool.run(name, input)Exampletool.run("lookup", "term") | post baseline registry only | Two arguments are recognized in this source snapshot; no built-in tool handler. |
| MCP client/tool execution | unsupported | No working built-in standalone Kaze MCP integration was established. |
4.6 Aliases and telemetry
| Name | Tag | Resolution |
|---|---|---|
lidar, camera, thermostat, probe | implemented | Resource aliases resolve to the sensor family. |
fan, mister, pump, relay, valve, motor, light | implemented | Resource aliases resolve to the device family. |
| Other unknown resource names | partial | Family resolution falls back to device; this does not prove a physical device exists. |
tools | post baseline registry only | Resolves to the tool family. |
agent, model, llm | post baseline registry only | Resolve to the ai family. |
Bare battery | partial | Recognized telemetry name; actual reading depends on the backend. |
Bare altitude | partial | Recognized telemetry name; actual reading depends on the backend. |
Bare heading | partial | Recognized telemetry name; actual reading depends on the backend. |
Bare speed | partial | Recognized telemetry name; actual reading depends on the backend. |
Bare position | partial | Recognized by the parser; the built-in simulator's telemetry lookup falls back to 0. |
Bare temperature | partial | Recognized telemetry name; the standalone sensor backend is unavailable. |
Bare humidity | partial | Recognized telemetry name; the standalone sensor backend is unavailable. |
Bare distance | partial | Recognized telemetry name; the standalone sensor backend is unavailable. |
Bare armed | partial | Recognized telemetry name; returned representation depends on the backend. |
Bare latitude | partial | Recognized telemetry name; actual reading depends on the backend. |
Bare longitude | partial | Recognized telemetry name; actual reading depends on the backend. |
Bare satellites | partial | Recognized by the parser; the built-in simulator's telemetry lookup falls back to 0. |
| Bare-telemetry resolution | partial | Each source file must identify exactly one hardware resource resolving to drone, rover, or sensor; merged imports do not fix ambiguity in that file. |
A division error
This arithmetic failure is uncatchable; try/otherwise handles only the listed host errors.
action main():
return 1 / 0E_KAZE_DIV05.1 Individual error codes
Catchable means recoverable by a Kaze try block when emitted by a capability call. Front-end failures occur before that block runs. CLI option parsing can also produce unstructured usage text without a Kaze error code.
| Code | Tag | Typical cause | Catchable? |
|---|---|---|---|
E_KAZE_PARSEExampleaction main() # missing colon | implemented | Lexer or grammar failure, indentation, malformed literal, or parser nesting limit. | No |
E_KAZE_CHECKExamplereturn missing_name # undefined | implemented | Semantic check failure, undefined name, capability declaration, arity, or filter termination. | No |
E_KAZE_COMPILE | implemented | Compiler failure, including excessive item slots or list literal size. | No |
E_KAZE_IMPORT | implemented | Import cycle, collision, or invalid import resolution condition. | No |
E_KAZE_ENTRYExamplekaze run example.kaze --entry missing | implemented | Missing explicitly selected item or ambiguous default routine. | No |
E_KAZE_IOExamplekaze check missing.kaze | implemented | Source or imported-file I/O failure. | No |
E_KAZE_FMT | implemented | Formatter failure or refusal to preserve source token meaning. | No |
E_KAZE_BADCODE | implemented | Invalid, incompatible, truncated, or unverifiable bytecode. | No |
E_KAZE_TRAP | implemented | An executed bytecode trap. | No |
E_KAZE_TYPEExamplereturn amount + 1 # with amount omitted | implemented | Invalid value type for an operation, field, index, or checked hardware argument. | No |
E_KAZE_RANGEExampledistance between vector(91, 0) and vector(1, 1) | implemented | Invalid geographic place or an out-of-range checked physical argument. | No |
E_KAZE_BOUNDSExamplereturn [1][2] | implemented | Invalid or out-of-range list, text, or point index. | No |
E_KAZE_DIV0Examplereturn 1 / 0 | implemented | Division or remainder by zero. | No |
E_KAZE_MATHExamplereturn sqrt(0 - 4) | implemented | Invalid real math, such as square root of a negative value. | No |
E_KAZE_OVERFLOW | implemented | Arithmetic or numeric operation produces a non-finite result. | No |
E_KAZE_STACK | implemented | Operand-stack or active recovery-handler limit exceeded. | No |
E_KAZE_MEMORY | partial | Arena or collection allocation fails; argument conversion has separate silent-nothing cases. | No |
E_TIMEOUTExamplekaze run loop.kaze --fuel 50 | implemented verified | Fuel exhaustion or an armed host deadline at a loop poll. | No |
E_CAP_UNDECLARED | implemented | Required family is absent from needs: at the runtime gate. | No |
E_CAP_MISSINGExampleneeds: log with no log grant | implemented post baseline | Any required family grant or configured backend is absent; unavailable built-in operations also return this code. | No |
E_CAP_DENIEDExamplea capability call without a valid policy.json | implemented post baseline | A policy is missing, malformed, unsupported, or denies the call; live drone actuation is disabled pending safety checks. | No |
E_SAFETY_VIOLATION | implemented | Safety error forwarded from an applicable host path. | No |
E_KAZE_LINK | implemented | Link connection, device configuration, or live I/O failure. | Yes, from a capability call |
E_KAZE_LINK_TIMEOUT | implemented | Live link did not respond within its applicable timeout. | Yes, from a capability call |
E_COMMAND_REJECTED | implemented | A vehicle/backend rejected a command. | Yes, from a capability call |
E_ARMING_DENIED | implemented | The vehicle did not reach the armed state or denied arming. | Yes, from a capability call |
E_KAZE_HOST | implemented | Explicitly classified operational host failure. | Yes, from a capability call |
E_KAZE_HOST_UNCLASSIFIED | implemented post baseline | An unknown or untyped host failure is not silently treated as a recoverable operational error. | No |
5.2 Error behavior
| Item | Tag | Behavior |
|---|---|---|
try recovery set | implemented | Exactly E_KAZE_LINK, E_KAZE_LINK_TIMEOUT, E_COMMAND_REJECTED, E_ARMING_DENIED, and E_KAZE_HOST are catchable from capability calls. |
| Unknown host error codes | implemented post baseline verified | Unknown or untyped host failures become E_KAZE_HOST_UNCLASSIFIED, which is not catchable. |
| Stack unwind | implemented | A caught error unwinds the operand stack and restores the verdict that existed at try entry; local changes are not rolled back. |
| Error location | partial | Parser errors have line/column; other failures may report an item line or line 0 where finer source location is unavailable. |
| JSON run success | implemented | --json produces a run report containing entry, value, actions, logs, instruction/fuel counts, ticks, optional verdict, and simulated_families. |
| JSON run failure | partial | kaze run --json still prints failures as text to stderr instead of a corresponding JSON diagnostic object. |
| CLI exits | implemented | Successful run exits 0; execution/front-end errors exit 1; usage/flag errors exit 2. |
| Required parameter diagnostics | target partial | Repository policy requires structured guidance, but standalone Kaze can bind missing input to nothing and later raise E_KAZE_TYPE. |
Bound an infinite loop
Fuel counts instructions; it does not bound time spent inside a blocking host call.
action main():
while 1 == 1:
let value = 1kaze run loop.kaze --fuel 50
# E_TIMEOUT| Limit or property | Tag | Current behavior |
|---|---|---|
Instruction fuelExamplekaze run loop.kaze --fuel 50 | implemented verified | Default 200,000 units shared by entry and hooks in one run; --fuel changes it. A requested 0 becomes 1. |
| String arena | implemented | Default 256 KiB of string bytes; runtime allocation can raise E_KAZE_MEMORY. |
| Collection heap | partial | Default 65,536 stored values; this counts collection values, not all allocation bytes or empty collection objects. |
| Operand stack | implemented | Maximum 256 values. |
Active try handlers | implemented | Maximum 32 active recovery handlers per item. |
| Parser expression nesting | implemented | Maximum 64 guarded expression levels. |
| Parser block nesting | implemented | Maximum 64 block levels. |
| Item local slots | implemented | Up to 255 compiled slots per item, including parameters and compiler-generated temporaries. |
List literal elementsExample[1, 2, 3] | implemented | Up to 255 elements in one source literal. |
| Capability-call arguments | implemented | Bytecode encodes at most 255; each registered operation usually has a much smaller arity in §4. |
| Link silence window | implemented | Between 1 and 4,294,967,295 milliseconds; larger/shorter values are refused. |
TicksExample--ticks 2 | implemented | Default 0; --ticks accepts an unsigned 32-bit value. |
Tick intervalExample--tick-ms 100 | implemented | Default 100 ms; --tick-ms accepts an unsigned 64-bit value. |
| Tick cleanup | implemented | String arena and collection heap are cleared after each supervisor tick; VM values do not persist across tick boundaries. |
| Blocking host call | partial | Fuel counts VM instructions, not time spent inside a blocking host call. |
| Host deadline | partial | An embedding host can arm the process-global deadline; loop-head polling checks it. The CLI does not expose a general deadline flag. |
.kazebc format | implemented verified | Standalone version 4; a compiled module contains flattened items, not runtime imports. |
| Bytecode verifier | implemented | Deserialization and execution validate structure, opcodes, indices, jumps, capability arity, and stack flow before execution. |
| Deterministic artifact | implemented verified | Repeated compilation of the same source/layout produced identical bytes locally; recorded external absolute paths can affect artifact origins. |
| Sofuu embedded artifact | unsupported | Embedded source format 2 (and legacy format 1) and standalone format 4 are not directly interchangeable. |
| Security compatibility | post baseline | The new gate and host defaults change which previously accepted runs succeed; bytecode format remains 4. A release/version compatibility decision remains open. |
Authorize local logging
The policy is loaded from the current working directory. The grant and declaration are separate.
{"deny": []}kaze run routine.kaze --entry main --cap log --fuel 5007.1 Commands
| Command | Tag | Behavior |
|---|---|---|
kaze run <file.kaze>Examplekaze run example.kaze --arg amount=4 | implemented | Parse, resolve imports, check, compile, verify, and execute source. |
kaze run <file.kazebc>Examplekaze run program.kazebc --arg amount=4 | implemented verified | Deserialize, verify, and execute standalone format-4 bytecode. |
kaze check <file.kaze>Examplekaze check example.kaze | implemented | Prepare/check source and imports without executing the program. |
kaze compile <file.kaze>Examplekaze compile example.kaze --out program.kazebc | implemented | Emit .kazebc; --out chooses the path. |
kaze fmt <file.kaze>Examplekaze fmt example.kaze --check | implemented | Print formatted source; --check and --write change formatter behavior. |
kaze bench <file>Examplekaze bench example.kaze --arg amount=4 --iterations 3 | implemented | Repeatedly run a prepared source or module and report timing; run only with policy-compliant workloads. |
kaze selftest | implemented post baseline | Run the scorecard using pure computation, bytecode validation, and gate refusals; it no longer implicitly runs a simulated mission. |
kaze repl | implemented | Interactive buffer and commands, subject to the same backend limitations. |
kaze version | implemented verified | Print kaze 1.0. |
kaze --version | implemented verified | Alternative version command. |
kaze --help | implemented | Print CLI help. |
kaze-lsp | implemented | Separate language-server binary over stdio; see TOOLING.md. |
7.2 CLI options
| Option | Tag | Default / meaning |
|---|---|---|
--entry NAMEExample--entry main | implemented | Entry name; default uses root main, then sole root routine. |
--arg NAME=VALUEExample--arg amount=4 | implemented verified | Repeatable argument. Parse value as JSON when possible; otherwise use text. |
--arg 0=VALUEExample--arg 0=4 | implemented | Numeric key binds by zero-based parameter position if no named binding takes precedence. |
--cap FAMILYExample--cap log | implemented post baseline | Repeatable family grant. It does not implicitly select a simulator or provide a missing backend. |
--cap FAMILY=BACKENDExample--cap drone=sim | partial | Grant and choose a backend; the standalone live host handles drone and device, with specific mapping requirements. |
--cap drone=sim | simulated post baseline | Explicitly select the labelled drone simulator for testing. |
--cap rover=sim | simulated post baseline | Explicitly select the labelled rover simulator for testing. |
| Drone UDP backend | live path unverified | --cap drone=udp:HOST:PORT binds a local UDP endpoint for MAVLink. |
| Drone UART backend | live path unverified | --cap drone=uart:/dev/device@baud; omitting @baud selects 57600. Requires the uart build feature. |
--pin NAME=LINEExample--pin fan=17 | live path unverified | Map a name to an unsigned 16-bit Linux GPIO line. |
--pwm NAME=CHIP:CHANNELExample--pwm fan=0:0 | live path unverified | Map a name to unsigned 16-bit PWM chip/channel numbers. |
--fuel NExample--fuel 500 | implemented | Unsigned instruction budget; default 200000, with a minimum effective value of 1. |
--ticks NExample--ticks 2 | implemented | Unsigned tick count; default 0. |
--tick-ms NExample--tick-ms 100 | implemented | Unsigned tick interval in milliseconds; default 100. |
--paceExample--ticks 2 --tick-ms 100 --pace | implemented | Sleep between ticks; disabled by default. |
--sim K=V[,K=V]Example--cap drone=sim --sim battery=15 | simulated | Repeatable simulator-state overrides; requires an explicit drone=sim or rover=sim testing backend. |
--no-policyExamplekaze run example.kaze --arg amount=4 --no-policy | implemented post baseline | Disables loading the policy file; capability calls still fail closed with E_CAP_DENIED. Pure computation can run. |
--jsonExamplekaze run example.kaze --arg amount=4 --json | implemented | JSON success report for run, timings for bench, and scorecard output where supported. |
--plainExamplekaze run example.kaze --arg amount=4 --plain | implemented | Plain-text run report. |
--out PATH, -o PATHExample--out program.kazebc | implemented | Output path for compile. |
--disasmExamplekaze compile example.kaze --disasm | implemented | Print compiled module disassembly instead of writing the artifact. |
--checkExamplekaze fmt example.kaze --check | implemented | For fmt, report whether input is already formatted. |
--write, -wExamplekaze fmt example.kaze --write | implemented | For fmt, write formatted source to the file. |
--iterations NExample--iterations 3 | implemented | For bench, number of iterations; default 20, minimum effective value 1. |
--help, -h, help | implemented | Help flag recognized by the shared flag parser; command-specific help behavior varies. |
--config PATH | unsupported | The standalone kaze CLI has no agent configuration-file option. Its flag parser treats unrecognized tokens as positionals rather than rejecting every unknown flag. |
| Positional routine values | unsupported | The CLI uses the first positional as the source/artifact path; routine values use --arg. |
7.3 Argument, policy, and environment configuration
| Setting | Tag | Current behavior |
|---|---|---|
Named JSON argumentExample--arg enabled=true | implemented | --arg amount=4, --arg enabled=true, --arg 'items=[1,2]', and --arg 'item={"x":1}' become the corresponding values. |
Text argumentExample--arg label=hello | implemented | If VALUE is not valid JSON, its raw text becomes a string. Quote shell arguments as needed. |
Duplicate argument keyExample--arg amount=1 --arg amount=4 | implemented | The later --arg replaces the earlier value for the same key. |
Named vs numeric keyExample--arg 0=1 --arg amount=4 | implemented | For a parameter, its named key is checked before its zero-based numeric key. |
| Missing argument | partial verified | Becomes nothing; later use can fail with E_KAZE_TYPE. No early structured missing-input guidance. |
| Argument allocation failure | partial | Conversion can substitute nothing when allocating an argument fails. |
policy.jsonExample{"deny": []} | implemented post baseline | The CLI reads this file from the current working directory. A valid file is required for capability calls; pure computation does not require one. |
Policy deny entryExample{"deny":["drone.arm"]} | implemented post baseline | deny must be an array of known family.operation, family.*, or * patterns; drone.link_lost is also recognized. |
| Malformed policy | post baseline implemented | The gate rejects missing/empty objects, malformed JSON, unknown fields, non-text entries, and unknown deny patterns; CLI parsing also rejects duplicate keys. |
KAZE_GPIO_ROOT | live path | Override the Linux GPIO sysfs root used by the hardware bus. |
KAZE_GPIO_CHIP | live path | Override the GPIO character-device path used by applicable hardware code. |
KAZE_PWM_ROOT | live path | Override the Linux PWM sysfs root used by the hardware bus. |
| UART feature | implemented | Serial transport requires building with the uart Cargo feature. |
| GPIO character-device feature | implemented | Character-device GPIO is behind the chardev Cargo feature. |
AGENT_<PARAM> routine binding | unsupported target | Required by repository policy for standalone agent binaries; not implemented by this standalone kaze CLI. |
SOFUU_* routine binding | unsupported target | Part of the repository's standalone-agent configuration target, not standalone kaze CLI parameter resolution. |
./agent.config.json | unsupported target | Part of the standalone-agent target; not loaded for Kaze CLI routine binding. |
| Signature defaults | unsupported target | The repository lists signatures at the bottom of the intended precedence hierarchy; current standalone signatures have no defaults. |
| Intended agent precedence | target | CLI flags/positionals > AGENT_<PARAM> / SOFUU_* environment > config file > routine signature. A Sofuu-compiled agent is a separate implementation and must be verified separately. |
7.4 Simulator state options
All entries in this table are simulated and are not real telemetry. Their use is constrained by RULES.md §1.9. These are documented to describe existing source behavior, not as a recommendation for non-robotics execution.
--sim key | Tag | Default / interpretation |
|---|---|---|
battery | simulated | 100. |
armed | simulated | false; true, 1, or yes are treated as true. |
on_ground | simulated | true; same boolean parsing as armed. |
altitude | simulated | 0 meters. |
lat | simulated | 0. |
lon | simulated | 0. |
heading | simulated | 0. |
speed | simulated | 0. |
temperature | simulated | 22. |
humidity | simulated | 45. |
distance | simulated | 2. |
front_distance | simulated | Alias that sets simulated distance. |
link_lost_after | simulated | No dropout by default; accepts a nonnegative millisecond time. |
link-lost-after | simulated | Alias for link_lost_after. |
link_lost | simulated | Alias for link_lost_after. |
7.5 REPL commands
| Command | Tag | Behavior |
|---|---|---|
.help | implemented | Show REPL command help. |
.needs family, ... | implemented | Add declarations used when the buffer has no needs: header. |
.cap family | implemented post baseline | Grant the family; this does not select a simulator. The REPL reads policy.json for capability calls. |
.cap drone=sim / .cap rover=sim | simulated post baseline | Explicitly grant and select a labelled robotics simulator for testing. |
.run [routine] | partial | Run buffered source with optional entry; default run options do not bind routine arguments. |
.clear | implemented | Clear the buffer, declarations, and grants. |
.list | implemented | Print declarations and buffered source. |
.exit, .quit | implemented | Leave the REPL. |
| Evidence | Tag | Scope |
|---|---|---|
| Offline build | verified | The current source compiled locally into a temporary target directory without downloading dependencies or model weights. |
| Pure language probes | verified | Version, named arguments, loops, arithmetic, points, mixed-unit behavior, literal modulo ambiguity, missing inputs, fuel, imports, and format-4 artifacts. |
| Capability safety tests | verified post baseline | Local logging, policy/grant refusals, unavailable backends, link-loss gating, physical-argument refusals, lazy link setup, and disabled live drone actuation were checked; drone and rover simulation were explicitly selected and labelled. |
| Compatibility and language tests | verified post baseline | Selected format-4 compatibility, module, REPL, benchmark, standard-library, and language tests passed with explicit policy and grants; robotic simulation was explicitly selected and labelled. |
| Capability examples | verified | Filter and drone recovery examples, all 40 registry operations in expression position, and the dotted-log statement limitation were checked by the front end only; their capabilities were not executed. |
| Real external operations | unverified | No AI, MCP, external tool, memory backend, or physical hardware was exercised for this inventory. |
| Full release gates | unverified partial | The full test, contract, and preflight suites include non-robotics stand-ins that must be migrated before they can run under RULES.md §1.9. Distribution artifacts have existing verification failures. |
| Published build | unverified | This source snapshot is not proof of the contents of any published binary. |
Primary implementation sources: lexer, parser, AST, checker, compiler, values, VM, capability registry, hardware gate, host dispatch, bytecode, run API, and CLI. The existing specification, module reference, compatibility notes, and tooling reference provide additional context; where they differ, the gaps are tagged above.
Keep the context close.
Read the source inventory and roadmap for details on open safety and compatibility work.