Sofuu / docs
OverviewStatus tagsSyntaxValues & unitsRoutinesCapabilitiesErrorsExecution limitsConfigurationEvidence
LANGUAGE REFERENCE STANDALONE 1.0

Kaze, in detail.

Everything in the current standalone language surface, from your first expression to the boundaries around a host call.

01 LANGUAGE 1.004 BYTECODE FORMAT373 INDEXED ENTRIES
i
Choose the right Kaze surface

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.

Capability statusStandalone AI, tool, memory, sensor, and alert backends are unavailable. Drone and rover simulation is explicitly selected and labelled for testing. Live drone actuation is disabled pending freshness checks.

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

01

Tag key

#

Every inventory row has at least one status tag. Tags describe this snapshot; IMPLEMENTED alone is a source-code observation, not proof of deployment.

TagMeaning
implementedPresent in the inspected standalone source for the stated scope.
verifiedAdditionally checked locally; the evidence section identifies pure checks, real local operations, or explicitly labelled robotics simulation.
partialPresent with a stated gap, restriction, or incomplete enforcement.
live pathA real hardware code path exists; a configured device and appropriate permissions are still required.
unverifiedThis inventory did not verify the stated physical device, external integration, or published artifact.
simulatedThe built-in path supplies simulated state or an imitation rather than a real external operation.
registry onlyThe name and arity are recognized, but the inspected built-in host has no matching implementation.
post baselineThis detail differs from the frozen standalone v1.0 baseline; the release compatibility decision remains open.
unsupportedNo corresponding general feature is implemented in this standalone surface.
targetA 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.

02

Syntax

#
Example

A small program

Pure computation · no capabilities required

example.kaze
action main(amount):
    let total = 0
    for each value in [1, 2, 3]:
        set total to total + value
    return total + amount
Terminal
kaze run example.kaze --arg amount=4 --plain
# main -> 10

1.1 Source structure and lexical rules

ItemTagExact form and behavior
File encodingExamplekaze check - < example.kazeimplementedUTF-8 source. kaze run - and kaze check - read source from stdin.
ProgramExampleaction main(): return 1implementedOptional 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"implementedneeds: and use lines can appear in either order before the first item. Each file permits at most one needs: line.
BlockExampleaction main(): return 1implemented verifiedA 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 1implementedSpaces are used; the formatter uses four spaces per level. Tabs in code outside strings/comments are rejected.
CommentsExample# This is a commentimplemented# outside a string starts a comment through the end of the line.
ContinuationExample[1, 2]implementedNewlines inside (...) or [...] continue the expression.
IdentifierExampletotal_countimplementedASCII [A-Za-z_][A-Za-z0-9_]*; names are case-sensitive.
Text literalExample"hello\nworld"implementedDouble-quoted, single-line text. Supported escapes: \n, \t, \", \\.
Number literalExample1.25implementedDecimal 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.
Punctuationimplemented:, (, ), ,, ., %, +, -, *, /, <, >, =, [, ]; plus <=, >=, ==, !=.
Semicolon and bracesunsupportedNo general semicolon statement separator, {...} block, or map literal syntax.

1.2 Header and declaration syntax

SyntaxTagMeaning and constraints
needs: family, familyExampleneeds: drone, logimplementedDeclare capability resources. Duplicate names in one header are rejected. A declaration is not itself a backend grant.
use "path.kaze"Exampleuse "helpers.kaze"implemented verifiedCompile-time include. The path must end in .kaze; relative paths resolve from the importing file.
action name(a, b):Exampleaction main(amount):implementedDeclare an executable named routine with positional signature names.
check name(a, b):Examplecheck valid(value):implementedDeclare a named check routine. Runtime entry binding works like an action.
filter name(a, b):Examplefilter gate(text):partial verifiedDeclare a policy-oriented routine; the checker allows a plain return, which can yield no verdict.
when condition:Examplewhen 1 == 1:implementedDeclare a hook evaluated on each requested supervisor tick.
every 100 ms:Exampleevery 100 ms:implementedDeclare 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 namesimplementedRejected within one file and on module merge. Hook names are generated.
Parameter defaults / annotationsunsupportedRoutine signatures contain names only; no default values or source type annotations.

1.3 Statements

SyntaxTagMeaning
let name = expressionExamplelet count = 1implemented verifiedBind a value in the current scope.
set name = expressionExampleset count = 2implementedReassign an existing binding.
set name to expressionExampleset count to 2implemented verifiedAlternative spelling for set.
if condition:Exampleif count > 0:implementedRun its indented block when the condition is true.
otherwise: after ifExampleif count > 0: return count otherwise: return 0implementedOptional alternative block.
for each item in values:Examplefor each item in [1, 2, 3]:implemented verifiedIterate over a list; the loop variable is local to its body.
while condition:Examplewhile count < 3:implementedRepeat while the condition is true, subject to the run's fuel and applicable deadline.
try:Exampletry: arm drone otherwise with error: return error.codeimplementedStart a protected block for the specific recoverable host errors in §5.
otherwise: after tryExampletry: arm drone otherwise: return 0implementedRequired recovery block; it can omit an error binding.
otherwise with error:Exampleotherwise with error: return error.codeimplementedRecovery block with error.code, error.message, and error.line.
returnExamplereturnimplementedEnd the current item with the runtime value nothing.
return expressionExamplereturn countimplemented verifiedEnd the current item with that value.
return to launchExamplereturn to launchimplementedCapability sentence for drone.rtl(); this is a host operation, not the ordinary return statement.
Expression statementExamplesin(0)implementedEvaluate an expression and discard its value unless it is a policy verdict.
break / continueunsupportedNo general loop-control statements.
Field or index assignmentunsupportedset record.field ... and set list[index] ... are not general assignment forms.

1.4 Expressions and operators

FormTagMeaning and restrictions
nameExamplecountimplementedRead a parameter or local binding; some unbound names can resolve as bare telemetry.
(expression)Example(2 + 3) * 4implementedGroup an expression.
[a, b, ...]Example[1, 2, 3]implementedOrdered list literal; at most 255 elements per literal.
value[index]Examplevalues[0]implementedZero-based read from a list, text, or point; index must be a nonnegative integer in range.
name.fieldExamplepoint.zimplementedRead a field from a named record or point. A missing record field returns nothing.
receiver.operation(args)Exampledrone.telemetry("battery")partialCall 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 verifiedRejected 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"implementedCharacter count for text, element count for lists, and Euclidean magnitude for a point.
-valueExample-3implementedNumeric negation; point negation is supported.
not valueExamplenot falseimplementedBoolean negation; the checker expects boolean where it knows the type.
a + bExample2 + 3implementedAdd numbers or points, or concatenate two text values.
a - bExample5 - 2implementedSubtract numbers or points.
a * bExample2 * 3implementedMultiply numbers or scale a point by a number.
a / bExample6 / 2implementedDivide numbers or divide a point by a number; zero divisor raises E_KAZE_DIV0.
a % bExample(5) % 2partial verifiedNumeric 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 < 2implementedOrdering comparisons for compatible numbers or text.
a > b, a >= bExample3 >= 2implementedOrdering comparisons for compatible numbers or text.
a == b, a != bExample2 == 2implementedEquality / inequality. Points compare components; lists and records compare their heap identities, not deep structural contents.
a and bExampletrue and falseimplementedShort-circuit conjunction; the right side is skipped if the left is false.
a or bExampletrue or falseimplementedShort-circuit disjunction; the right side is skipped if the left is true.
routine(args)unsupportedNo direct call from one user-defined Kaze routine to another. Use --entry to select a routine.
Chained comparisonsunsupportedThe grammar handles one comparison at a time; do not rely on a < b < c.
String interpolationunsupportedBuild 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

SyntaxTagResult and constraints
vector(x, y)Examplevector(1, 2)implementedCreate a point with z = 0.
vector(x, y, z)Examplevector(1, 2, 3)implemented verifiedCreate a point from three numeric components.
distance between a and bExampledistance between vector(0, 0) and vector(1, 1)implementedGreat-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)implementedGround distance combined with altitude difference.
bearing of offsetExamplebearing of vector(1, 2)implementedCompass bearing of a local vector in degrees: north 0, east 90.
bearing from a to bExamplebearing from vector(0, 0) to vector(1, 1)implementedInitial compass bearing between two geographic points.
bearing to targetExamplebearing to vector(1, 1)partialUses 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)implementedSine of a number in radians.
cos(x)Examplecos(0)implementedCosine of a number in radians.
atan2(y, x)Exampleatan2(1, 1)implementedTwo-argument arctangent; result is radians.
sqrt(x)Examplesqrt(9)implemented verifiedSquare root; a negative input raises E_KAZE_MATH.
x in radiansExample180 in radiansimplementedConvert degrees to radians.
x in degreesExample3.141592653589793 in degreesimplementedConvert radians to degrees.
link lost for 3 secondsExamplelink lost for 3 secondspartialBoolean 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"partialLowers to policy.detects(kind, text); detector behavior depends on the host.
recall memories matching queryExamplerecall memories matching "greeting"registry onlyLowers 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.

SentenceTagLowers to
log valueExamplelog "ready"implementedlog.info(value).
log info valueExamplelog info "ready"implementedlog.info(value).
log warn value / log warning valueExamplelog warning "check"implementedlog.warn(value).
log error valueExamplelog error "failed"implementedlog.error(value).
log debug valueExamplelog debug "detail"implementedlog.debug(value).
send alert valueExamplesend alert "ready"implementedalert.send(value).
remember value as labelExampleremember "hello" as "greeting"implementedmemory.save(label, value).
recall memories matching queryExamplerecall memories matching "greeting"implementedmemory.recall(query).
allow / allow valueExampleallow "accepted"implementedpolicy.allow() / policy.allow(value) and terminate the item.
reject with reasonExamplereject with "too long"implementedpolicy.reject(reason) and terminate the item.
arm droneExamplearm droneimplementeddrone.arm(); the noun resolves to its family.
takeoff to heightExampletakeoff to 10 metersimplementeddrone.takeoff(height).
fly to pointExamplefly to vector(47.6, 8.5, 15)implementeddrone.goto(point).
fly to point at altitudeExamplefly to vector(47.6, 8.5, 0) at 15 metersimplementeddrone.goto(point, altitude).
land / land droneExampleland droneimplementeddrone.land().
hold / hold positionExamplehold positionimplementeddrone.hold().
return to launchExamplereturn to launchimplementeddrone.rtl().
stop drone / stop roverExamplestop roverimplemented<family>.stop().
drive / drive forwardExampledrive forward at 1 m/simplementedrover.forward(); at speed supplies a speed.
drive backwardExampledrive backward at 1 m/simplementedrover.backward(); at speed supplies a speed.
turn left by degreesExampleturn left by 90 degreesimplementedrover.turn_left(degrees).
turn right by degreesExampleturn right by 90 degreesimplementedrover.turn_right(degrees).
turn on nameExampleturn on fanimplementeddevice.set_relay("name", true).
turn off nameExampleturn off fanimplementeddevice.set_relay("name", false).
pulse name for durationExamplepulse fan for 2 secondsimplementeddevice.pulse("name", duration).
03

Values and units

#
Example

Lists, points, and a record

Records can enter as JSON arguments; record literals are not supported.

values.kaze
action main(item):
    let values = [2, 4, 6]
    let point = vector(1, 2, 3)
    return item.count + values[0] + point.z
Terminal
kaze run values.kaze --arg 'item={"count":5}' --plain
# main -> 10

2.1 Runtime values

ValueTagCreation, access, and behavior
NumberExample12 · 3.5implementedFinite f64; for example 12, 3.5, or a numeric --arg. Arithmetic can raise overflow or division errors.
TextExample"hello"implementedUTF-8, for example "hello"; text concatenation uses +. Indexing and length use Unicode scalar values, not bytes or grapheme clusters.
BooleanExampletrue · falseimplementedSource 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}'partialA JSON object argument or host can supply a record. Read name.field; no record literal or field assignment.
Point/vectorExamplevector(1, 2, 3)implementedvector(x, y) or vector(x, y, z). Read indexes 0, 1, 2 or named components below.
Nothing/unitExamplereturnimplementedRuntime value from an empty return, a missing field, JSON null, or a missing parameter. No general nothing source literal.
Error recordExampleotherwise with err: … err.codeimplementedIn a recovery block, .code and .message are text and .line is a number.
Point componentTagEquivalent names
First componentExamplepoint.ximplemented.x, .lat, .latitude, or [0].
Second componentExamplepoint.yimplemented.y, .lon, .longitude, or [1].
Third componentExamplepoint.zimplemented.z, .alt, .altitude, or [2].
Geographic placeimplementedSpatial distance/bearing checks latitude -90..90 and longitude -180..180; invalid places raise E_KAZE_RANGE.

2.2 Numeric literal units

UnitTagAccepted suffixesRepresentation
DistanceExample10 metersimplementedm, meter, metersNumeric value in meters.
SpeedExample1 m/simplementedm/sNumeric value in meters per second.
AngleExample90 degreesimplementeddeg, degree, degreesNumeric value in degrees.
TimeExample3 secondsimplementeds, sec, second, secondsNumeric value in seconds.
MillisecondsExample500 msimplementedms, millisecond, millisecondsNormalized to seconds: 500 ms becomes 0.5.
PercentageExample20%implemented%, percentWhole-number convention: 20% is 20, not 0.2.
Dimensional mismatch checkingpartial verifiedAny unit combinationThe current checker accepts 1 meters < 1 seconds; units are not retained as runtime tags. Do not assume dimensional safety.
Arbitrary/user-defined unitsunsupported—No general unit declaration or conversion system.
04

Routines, entries, and scheduling

#
Example

An entry and a periodic hook

Hooks run only when ticks are requested. Logging requires a grant and valid policy.

routine.kaze
needs: log

action main():
    log "starting"

every 100 ms:
    log "tick"
Terminal
kaze run routine.kaze --cap log --ticks 2 --tick-ms 100
ItemTagBehavior
ActionExampleaction main(): return 1implementedA named action may return a value or nothing.
CheckExamplecheck valid(value): return value > 0implementedA named check is selected and bound like an action; it has no separate mandatory boolean-return rule.
FilterExamplefilter gate(text): allow textpartial verifiedIntended to stop at allow or reject. A plain return also passes the current checker and can yield a null verdict.
Explicit entryExample--entry mainimplemented verified--entry name selects a named item, including an imported item. Missing names give E_KAZE_ENTRY.
Root mainimplementedWithout --entry, a main from the root file is preferred.
Single root routineimplementedWithout root main, the sole root action/check/filter is selected.
Multiple root routinesimplementedWithout an explicit entry or root main, ambiguous selection raises E_KAZE_ENTRY.
Hooks-only rootimplementedCan run with no entry; hooks require ticks to execute.
Imported implicit entryunsupportedImported routines do not become the implicit root entry.
ParametersExample--arg amount=4partialBound by name or numeric key in --arg. Missing values become nothing instead of an early missing-parameter diagnostic.
when hookExamplewhen 1 == 1:implementedPredicate runs for each requested tick; body runs when true.
every hookExampleevery 100 ms:implementedRuns when period divides virtual tick time. Time begins at 0, so a positive period is initially due.
Tick pacingimplemented--pace sleeps between ticks; without it scheduling advances virtual time without a sleep.
Hook statepartialVM locals/stack are recreated for each item; arena and heap are cleared after each tick. Host state can remain separate.
Routine callsunsupportedA routine cannot directly invoke another routine using ordinary call syntax.
Runtime imports / namespacesunsupporteduse is an include at compilation, with a shared global item namespace.
Import cycle / collisionimplementedCycles and duplicate item names fail. Shared dependencies are included once.

Example: pure action

kaze
action main(amount):
    let total = 0
    for each value in [1, 2, 3]:
        set total to total + value
    return total + amount

kaze run example.kaze --arg amount=4 --plain returns 10.

Example: filter and error recovery

kaze
needs: policy

filter limit_length(text):
    if length of text > 120:
        reject with "too long"
    otherwise:
        allow text
kaze
needs: drone

action recover():
    try:
        arm drone
    otherwise with problem:
        return problem.code

when link lost for 3 seconds:
    return to launch

The examples were checked without executing their capabilities. Actual drone operations need an authorized, configured backend.

05

Capabilities

#
Example

Explicit drone simulation

Testing only · this is simulated, not a physical flight. A valid policy.json is required.

simulation.kaze
needs: drone

action main():
    arm drone
    takeoff to 10 meters
    return to launch
Terminal
kaze run simulation.kaze --cap drone=sim --plain

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

GateTagCurrent behavior
H-1: declarationimplementedAn undeclared family is rejected; the checker can reject it before execution.
H-2: grantimplemented post baseline verifiedRequires an explicit host grant for every capability family.
H-3: policyimplemented post baseline verifiedMissing, malformed, unsupported, or denying policy causes E_CAP_DENIED. --no-policy does not bypass this gate.
H-4: argumentspartialSelected physical arguments have type/range checks and are rejected rather than clamped; coverage is not universal.
Default hostimplemented post baselineNo physical or simulated backend is selected implicitly. Missing backends return E_CAP_MISSING.
Simulator selectionimplemented post baseline verifieddrone=sim and rover=sim must be selected explicitly for testing; run reports identify selected simulators.
Live host fallbackimplemented post baseline verifiedUnconfigured sensor, device, alert, memory, AI, and tool operations return unavailable errors rather than simulated success.
Link-loss gateimplemented post baseline verifiedLink monitoring checks the drone declaration, grant, policy, and backend before reading the host.
Lazy live linkimplemented post baseline verifiedThe live drone connection opens only after the relevant VM gate approves the operation.
Live telemetry freshnesspartial targetThe 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 actuationpost baseline verified unsupportedThe 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 executionunverifiedThe 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.

OperationTagArguments and behavior
drone.arm()Examplearm dronelive path unverifiedNo arguments; request arming and wait for armed telemetry on the live path.
drone.takeoff(height)Exampletakeoff to 10 meterslive path unverifiedOne number in meters; gate checks 0..500.
drone.goto(target)Examplefly to vector(47.6, 8.5, 15)live path unverified partialOne 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 meterslive path unverifiedTwo 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 unverifiedThree numeric arguments; latitude is checked -90..90, longitude -180..180, and altitude 0..500 meters.
drone.land()Exampleland dronelive path unverifiedNo arguments; request landing.
drone.rtl()Examplereturn to launchlive path unverifiedNo arguments; request return to launch.
drone.hold()Examplehold positionlive path unverifiedNo arguments; request hold/loiter.
drone.stop()Examplestop dronelive path unverifiedNo arguments; live path maps to hold/loiter.
drone.telemetry(field)Exampledrone.telemetry("battery")live path unverifiedOne 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.

OperationTagArguments and behavior
rover.forward()Exampledrive forwardsimulatedNo speed argument; simulator uses its own default.
rover.forward(speed)Exampledrive forward at 1.2 m/ssimulatedOne speed; supplied value is checked 0..10 m/s.
rover.backward()Exampledrive backwardsimulatedNo speed argument; simulator uses its own default.
rover.backward(speed)Exampledrive backward at 1 m/ssimulatedOne speed; supplied value is checked 0..10 m/s.
rover.turn_left(angle)Exampleturn left by 90 degreessimulatedOne angle in degrees.
rover.turn_right(angle)Exampleturn right by 90 degreessimulatedOne angle in degrees.
rover.stop()Examplestop roversimulatedNo arguments.
rover.telemetry(field)Examplerover.telemetry("speed")simulatedOne field name.
sensor.temperature()Examplesensor.temperature()registry onlyNo arguments; built-in host returns E_CAP_MISSING.
sensor.humidity()Examplesensor.humidity()registry onlyNo arguments; built-in host returns E_CAP_MISSING.
sensor.distance()Examplesensor.distance()registry onlyNo arguments; built-in host returns E_CAP_MISSING.
sensor.front_distance()Examplelidar.front_distance()registry onlyNo arguments; built-in host returns E_CAP_MISSING.
sensor.read(name)Examplesensor.read("ambient")registry onlyOne name or pin; built-in host returns E_CAP_MISSING.
sensor.telemetry(field)Examplesensor.telemetry("temperature")registry onlyOne 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.

OperationTagArguments and behavior
device.set_relay(name, on)Exampleturn on fanlive path unverifiedName and boolean or finite numeric state; live Linux GPIO requires a named pin.
device.pulse(name, seconds)Examplepulse fan for 2 secondslive path unverifiedName and duration; gate checks 0..60 seconds.
device.read_gpio(name)Exampledevice.read_gpio("fan")live path partial unverifiedOne 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 unverifiedName and PWM percentage; gate checks 0..100. A named PWM channel is required for the live PWM path.
Missing device mappingimplemented post baselineWithout a suitable live GPIO/PWM mapping, device operations return E_CAP_MISSING.

4.5 Memory, policy, logging, alerts, AI, and tools

OperationTagArguments and current behavior
memory.save(label, value)Exampleremember "hello" as "greeting"registry onlyTwo arguments; the standalone built-in host returns E_CAP_MISSING.
memory.recall(query)Examplerecall memories matching "greeting"registry onlyOne argument; the standalone built-in host returns E_CAP_MISSING.
policy.detects(kind, text)Examplepolicy detects secrets in "sample"partialTwo 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")partialAlias operation with the same built-in detection behavior.
policy.allow()ExampleallowimplementedVM records an allow verdict with nothing.
policy.allow(value)Exampleallow "accepted"implementedVM records an allow verdict with the rendered value.
policy.reject(reason)Examplereject with "too long"implementedVM records a reject verdict with the reason.
log.info(value)Examplelog "started"implementedOne argument; captured in the run report's logs.
log.warn(value)Examplelog warning "check"implementedOne argument; captured at warning level.
log.error(value)Examplelog error "failed"implementedOne argument; captured at error level.
log.debug(value)Examplelog debug "detail"implementedOne argument; captured at debug level.
alert.send(text)Examplesend alert "ready"registry onlyOne argument; the built-in host returns E_CAP_MISSING instead of pretending to deliver.
ai.prompt(text)Exampleai.prompt("summarize")post baseline registry onlyOne argument is recognized in this source snapshot; no built-in inference handler.
ai.complete(text)Exampleai.complete("summarize")post baseline registry onlyOne argument is recognized in this source snapshot; no built-in inference handler.
ai.classify(text, classes)Exampleai.classify("hello", ["greeting", "other"])post baseline registry onlyTwo arguments are recognized in this source snapshot; no built-in classifier handler.
tool.call(name)Exampletool.call("lookup")post baseline registry onlyOne argument is recognized in this source snapshot; no built-in tool handler.
tool.call(name, input)Exampletool.call("lookup", "term")post baseline registry onlyTwo arguments are recognized in this source snapshot; no built-in tool handler.
tool.run(name)Exampletool.run("lookup")post baseline registry onlyOne argument is recognized in this source snapshot; no built-in tool handler.
tool.run(name, input)Exampletool.run("lookup", "term")post baseline registry onlyTwo arguments are recognized in this source snapshot; no built-in tool handler.
MCP client/tool executionunsupportedNo working built-in standalone Kaze MCP integration was established.

4.6 Aliases and telemetry

NameTagResolution
lidar, camera, thermostat, probeimplementedResource aliases resolve to the sensor family.
fan, mister, pump, relay, valve, motor, lightimplementedResource aliases resolve to the device family.
Other unknown resource namespartialFamily resolution falls back to device; this does not prove a physical device exists.
toolspost baseline registry onlyResolves to the tool family.
agent, model, llmpost baseline registry onlyResolve to the ai family.
Bare batterypartialRecognized telemetry name; actual reading depends on the backend.
Bare altitudepartialRecognized telemetry name; actual reading depends on the backend.
Bare headingpartialRecognized telemetry name; actual reading depends on the backend.
Bare speedpartialRecognized telemetry name; actual reading depends on the backend.
Bare positionpartialRecognized by the parser; the built-in simulator's telemetry lookup falls back to 0.
Bare temperaturepartialRecognized telemetry name; the standalone sensor backend is unavailable.
Bare humiditypartialRecognized telemetry name; the standalone sensor backend is unavailable.
Bare distancepartialRecognized telemetry name; the standalone sensor backend is unavailable.
Bare armedpartialRecognized telemetry name; returned representation depends on the backend.
Bare latitudepartialRecognized telemetry name; actual reading depends on the backend.
Bare longitudepartialRecognized telemetry name; actual reading depends on the backend.
Bare satellitespartialRecognized by the parser; the built-in simulator's telemetry lookup falls back to 0.
Bare-telemetry resolutionpartialEach source file must identify exactly one hardware resource resolving to drone, rover, or sensor; merged imports do not fix ambiguity in that file.
06

Errors and recovery

#
Example

A division error

This arithmetic failure is uncatchable; try/otherwise handles only the listed host errors.

division.kaze
action main():
    return 1 / 0
Result
E_KAZE_DIV0

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

CodeTagTypical causeCatchable?
E_KAZE_PARSEExampleaction main() # missing colonimplementedLexer or grammar failure, indentation, malformed literal, or parser nesting limit.No
E_KAZE_CHECKExamplereturn missing_name # undefinedimplementedSemantic check failure, undefined name, capability declaration, arity, or filter termination.No
E_KAZE_COMPILEimplementedCompiler failure, including excessive item slots or list literal size.No
E_KAZE_IMPORTimplementedImport cycle, collision, or invalid import resolution condition.No
E_KAZE_ENTRYExamplekaze run example.kaze --entry missingimplementedMissing explicitly selected item or ambiguous default routine.No
E_KAZE_IOExamplekaze check missing.kazeimplementedSource or imported-file I/O failure.No
E_KAZE_FMTimplementedFormatter failure or refusal to preserve source token meaning.No
E_KAZE_BADCODEimplementedInvalid, incompatible, truncated, or unverifiable bytecode.No
E_KAZE_TRAPimplementedAn executed bytecode trap.No
E_KAZE_TYPEExamplereturn amount + 1 # with amount omittedimplementedInvalid value type for an operation, field, index, or checked hardware argument.No
E_KAZE_RANGEExampledistance between vector(91, 0) and vector(1, 1)implementedInvalid geographic place or an out-of-range checked physical argument.No
E_KAZE_BOUNDSExamplereturn [1][2]implementedInvalid or out-of-range list, text, or point index.No
E_KAZE_DIV0Examplereturn 1 / 0implementedDivision or remainder by zero.No
E_KAZE_MATHExamplereturn sqrt(0 - 4)implementedInvalid real math, such as square root of a negative value.No
E_KAZE_OVERFLOWimplementedArithmetic or numeric operation produces a non-finite result.No
E_KAZE_STACKimplementedOperand-stack or active recovery-handler limit exceeded.No
E_KAZE_MEMORYpartialArena or collection allocation fails; argument conversion has separate silent-nothing cases.No
E_TIMEOUTExamplekaze run loop.kaze --fuel 50implemented verifiedFuel exhaustion or an armed host deadline at a loop poll.No
E_CAP_UNDECLAREDimplementedRequired family is absent from needs: at the runtime gate.No
E_CAP_MISSINGExampleneeds: log with no log grantimplemented post baselineAny 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.jsonimplemented post baselineA policy is missing, malformed, unsupported, or denies the call; live drone actuation is disabled pending safety checks.No
E_SAFETY_VIOLATIONimplementedSafety error forwarded from an applicable host path.No
E_KAZE_LINKimplementedLink connection, device configuration, or live I/O failure.Yes, from a capability call
E_KAZE_LINK_TIMEOUTimplementedLive link did not respond within its applicable timeout.Yes, from a capability call
E_COMMAND_REJECTEDimplementedA vehicle/backend rejected a command.Yes, from a capability call
E_ARMING_DENIEDimplementedThe vehicle did not reach the armed state or denied arming.Yes, from a capability call
E_KAZE_HOSTimplementedExplicitly classified operational host failure.Yes, from a capability call
E_KAZE_HOST_UNCLASSIFIEDimplemented post baselineAn unknown or untyped host failure is not silently treated as a recoverable operational error.No

5.2 Error behavior

ItemTagBehavior
try recovery setimplementedExactly 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 codesimplemented post baseline verifiedUnknown or untyped host failures become E_KAZE_HOST_UNCLASSIFIED, which is not catchable.
Stack unwindimplementedA caught error unwinds the operand stack and restores the verdict that existed at try entry; local changes are not rolled back.
Error locationpartialParser errors have line/column; other failures may report an item line or line 0 where finer source location is unavailable.
JSON run successimplemented--json produces a run report containing entry, value, actions, logs, instruction/fuel counts, ticks, optional verdict, and simulated_families.
JSON run failurepartialkaze run --json still prints failures as text to stderr instead of a corresponding JSON diagnostic object.
CLI exitsimplementedSuccessful run exits 0; execution/front-end errors exit 1; usage/flag errors exit 2.
Required parameter diagnosticstarget partialRepository policy requires structured guidance, but standalone Kaze can bind missing input to nothing and later raise E_KAZE_TYPE.
07

Execution limits and bytecode

#
Example

Bound an infinite loop

Fuel counts instructions; it does not bound time spent inside a blocking host call.

loop.kaze
action main():
    while 1 == 1:
        let value = 1
Terminal
kaze run loop.kaze --fuel 50
# E_TIMEOUT
Limit or propertyTagCurrent behavior
Instruction fuelExamplekaze run loop.kaze --fuel 50implemented verifiedDefault 200,000 units shared by entry and hooks in one run; --fuel changes it. A requested 0 becomes 1.
String arenaimplementedDefault 256 KiB of string bytes; runtime allocation can raise E_KAZE_MEMORY.
Collection heappartialDefault 65,536 stored values; this counts collection values, not all allocation bytes or empty collection objects.
Operand stackimplementedMaximum 256 values.
Active try handlersimplementedMaximum 32 active recovery handlers per item.
Parser expression nestingimplementedMaximum 64 guarded expression levels.
Parser block nestingimplementedMaximum 64 block levels.
Item local slotsimplementedUp to 255 compiled slots per item, including parameters and compiler-generated temporaries.
List literal elementsExample[1, 2, 3]implementedUp to 255 elements in one source literal.
Capability-call argumentsimplementedBytecode encodes at most 255; each registered operation usually has a much smaller arity in §4.
Link silence windowimplementedBetween 1 and 4,294,967,295 milliseconds; larger/shorter values are refused.
TicksExample--ticks 2implementedDefault 0; --ticks accepts an unsigned 32-bit value.
Tick intervalExample--tick-ms 100implementedDefault 100 ms; --tick-ms accepts an unsigned 64-bit value.
Tick cleanupimplementedString arena and collection heap are cleared after each supervisor tick; VM values do not persist across tick boundaries.
Blocking host callpartialFuel counts VM instructions, not time spent inside a blocking host call.
Host deadlinepartialAn embedding host can arm the process-global deadline; loop-head polling checks it. The CLI does not expose a general deadline flag.
.kazebc formatimplemented verifiedStandalone version 4; a compiled module contains flattened items, not runtime imports.
Bytecode verifierimplementedDeserialization and execution validate structure, opcodes, indices, jumps, capability arity, and stack flow before execution.
Deterministic artifactimplemented verifiedRepeated compilation of the same source/layout produced identical bytes locally; recorded external absolute paths can affect artifact origins.
Sofuu embedded artifactunsupportedEmbedded source format 2 (and legacy format 1) and standalone format 4 are not directly interchangeable.
Security compatibilitypost baselineThe new gate and host defaults change which previously accepted runs succeed; bytecode format remains 4. A release/version compatibility decision remains open.
08

Configuration and command line

#
Example

Authorize local logging

The policy is loaded from the current working directory. The grant and declaration are separate.

policy.json
{"deny": []}
Terminal
kaze run routine.kaze --entry main --cap log --fuel 500

7.1 Commands

CommandTagBehavior
kaze run <file.kaze>Examplekaze run example.kaze --arg amount=4implementedParse, resolve imports, check, compile, verify, and execute source.
kaze run <file.kazebc>Examplekaze run program.kazebc --arg amount=4implemented verifiedDeserialize, verify, and execute standalone format-4 bytecode.
kaze check <file.kaze>Examplekaze check example.kazeimplementedPrepare/check source and imports without executing the program.
kaze compile <file.kaze>Examplekaze compile example.kaze --out program.kazebcimplementedEmit .kazebc; --out chooses the path.
kaze fmt <file.kaze>Examplekaze fmt example.kaze --checkimplementedPrint formatted source; --check and --write change formatter behavior.
kaze bench <file>Examplekaze bench example.kaze --arg amount=4 --iterations 3implementedRepeatedly run a prepared source or module and report timing; run only with policy-compliant workloads.
kaze selftestimplemented post baselineRun the scorecard using pure computation, bytecode validation, and gate refusals; it no longer implicitly runs a simulated mission.
kaze replimplementedInteractive buffer and commands, subject to the same backend limitations.
kaze versionimplemented verifiedPrint kaze 1.0.
kaze --versionimplemented verifiedAlternative version command.
kaze --helpimplementedPrint CLI help.
kaze-lspimplementedSeparate language-server binary over stdio; see TOOLING.md.

7.2 CLI options

OptionTagDefault / meaning
--entry NAMEExample--entry mainimplementedEntry name; default uses root main, then sole root routine.
--arg NAME=VALUEExample--arg amount=4implemented verifiedRepeatable argument. Parse value as JSON when possible; otherwise use text.
--arg 0=VALUEExample--arg 0=4implementedNumeric key binds by zero-based parameter position if no named binding takes precedence.
--cap FAMILYExample--cap logimplemented post baselineRepeatable family grant. It does not implicitly select a simulator or provide a missing backend.
--cap FAMILY=BACKENDExample--cap drone=simpartialGrant and choose a backend; the standalone live host handles drone and device, with specific mapping requirements.
--cap drone=simsimulated post baselineExplicitly select the labelled drone simulator for testing.
--cap rover=simsimulated post baselineExplicitly select the labelled rover simulator for testing.
Drone UDP backendlive path unverified--cap drone=udp:HOST:PORT binds a local UDP endpoint for MAVLink.
Drone UART backendlive path unverified--cap drone=uart:/dev/device@baud; omitting @baud selects 57600. Requires the uart build feature.
--pin NAME=LINEExample--pin fan=17live path unverifiedMap a name to an unsigned 16-bit Linux GPIO line.
--pwm NAME=CHIP:CHANNELExample--pwm fan=0:0live path unverifiedMap a name to unsigned 16-bit PWM chip/channel numbers.
--fuel NExample--fuel 500implementedUnsigned instruction budget; default 200000, with a minimum effective value of 1.
--ticks NExample--ticks 2implementedUnsigned tick count; default 0.
--tick-ms NExample--tick-ms 100implementedUnsigned tick interval in milliseconds; default 100.
--paceExample--ticks 2 --tick-ms 100 --paceimplementedSleep between ticks; disabled by default.
--sim K=V[,K=V]Example--cap drone=sim --sim battery=15simulatedRepeatable simulator-state overrides; requires an explicit drone=sim or rover=sim testing backend.
--no-policyExamplekaze run example.kaze --arg amount=4 --no-policyimplemented post baselineDisables loading the policy file; capability calls still fail closed with E_CAP_DENIED. Pure computation can run.
--jsonExamplekaze run example.kaze --arg amount=4 --jsonimplementedJSON success report for run, timings for bench, and scorecard output where supported.
--plainExamplekaze run example.kaze --arg amount=4 --plainimplementedPlain-text run report.
--out PATH, -o PATHExample--out program.kazebcimplementedOutput path for compile.
--disasmExamplekaze compile example.kaze --disasmimplementedPrint compiled module disassembly instead of writing the artifact.
--checkExamplekaze fmt example.kaze --checkimplementedFor fmt, report whether input is already formatted.
--write, -wExamplekaze fmt example.kaze --writeimplementedFor fmt, write formatted source to the file.
--iterations NExample--iterations 3implementedFor bench, number of iterations; default 20, minimum effective value 1.
--help, -h, helpimplementedHelp flag recognized by the shared flag parser; command-specific help behavior varies.
--config PATHunsupportedThe 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 valuesunsupportedThe CLI uses the first positional as the source/artifact path; routine values use --arg.

7.3 Argument, policy, and environment configuration

SettingTagCurrent behavior
Named JSON argumentExample--arg enabled=trueimplemented--arg amount=4, --arg enabled=true, --arg 'items=[1,2]', and --arg 'item={"x":1}' become the corresponding values.
Text argumentExample--arg label=helloimplementedIf VALUE is not valid JSON, its raw text becomes a string. Quote shell arguments as needed.
Duplicate argument keyExample--arg amount=1 --arg amount=4implementedThe later --arg replaces the earlier value for the same key.
Named vs numeric keyExample--arg 0=1 --arg amount=4implementedFor a parameter, its named key is checked before its zero-based numeric key.
Missing argumentpartial verifiedBecomes nothing; later use can fail with E_KAZE_TYPE. No early structured missing-input guidance.
Argument allocation failurepartialConversion can substitute nothing when allocating an argument fails.
policy.jsonExample{"deny": []}implemented post baselineThe 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 baselinedeny must be an array of known family.operation, family.*, or * patterns; drone.link_lost is also recognized.
Malformed policypost baseline implementedThe gate rejects missing/empty objects, malformed JSON, unknown fields, non-text entries, and unknown deny patterns; CLI parsing also rejects duplicate keys.
KAZE_GPIO_ROOTlive pathOverride the Linux GPIO sysfs root used by the hardware bus.
KAZE_GPIO_CHIPlive pathOverride the GPIO character-device path used by applicable hardware code.
KAZE_PWM_ROOTlive pathOverride the Linux PWM sysfs root used by the hardware bus.
UART featureimplementedSerial transport requires building with the uart Cargo feature.
GPIO character-device featureimplementedCharacter-device GPIO is behind the chardev Cargo feature.
AGENT_<PARAM> routine bindingunsupported targetRequired by repository policy for standalone agent binaries; not implemented by this standalone kaze CLI.
SOFUU_* routine bindingunsupported targetPart of the repository's standalone-agent configuration target, not standalone kaze CLI parameter resolution.
./agent.config.jsonunsupported targetPart of the standalone-agent target; not loaded for Kaze CLI routine binding.
Signature defaultsunsupported targetThe repository lists signatures at the bottom of the intended precedence hierarchy; current standalone signatures have no defaults.
Intended agent precedencetargetCLI 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 keyTagDefault / interpretation
batterysimulated100.
armedsimulatedfalse; true, 1, or yes are treated as true.
on_groundsimulatedtrue; same boolean parsing as armed.
altitudesimulated0 meters.
latsimulated0.
lonsimulated0.
headingsimulated0.
speedsimulated0.
temperaturesimulated22.
humiditysimulated45.
distancesimulated2.
front_distancesimulatedAlias that sets simulated distance.
link_lost_aftersimulatedNo dropout by default; accepts a nonnegative millisecond time.
link-lost-aftersimulatedAlias for link_lost_after.
link_lostsimulatedAlias for link_lost_after.

7.5 REPL commands

CommandTagBehavior
.helpimplementedShow REPL command help.
.needs family, ...implementedAdd declarations used when the buffer has no needs: header.
.cap familyimplemented post baselineGrant the family; this does not select a simulator. The REPL reads policy.json for capability calls.
.cap drone=sim / .cap rover=simsimulated post baselineExplicitly grant and select a labelled robotics simulator for testing.
.run [routine]partialRun buffered source with optional entry; default run options do not bind routine arguments.
.clearimplementedClear the buffer, declarations, and grants.
.listimplementedPrint declarations and buffered source.
.exit, .quitimplementedLeave the REPL.
09

Evidence and maintenance

#
EvidenceTagScope
Offline buildverifiedThe current source compiled locally into a temporary target directory without downloading dependencies or model weights.
Pure language probesverifiedVersion, named arguments, loops, arithmetic, points, mixed-unit behavior, literal modulo ambiguity, missing inputs, fuel, imports, and format-4 artifacts.
Capability safety testsverified post baselineLocal 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 testsverified post baselineSelected 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 examplesverifiedFilter 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 operationsunverifiedNo AI, MCP, external tool, memory backend, or physical hardware was exercised for this inventory.
Full release gatesunverified partialThe 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 buildunverifiedThis 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 EXPLORING

Keep the context close.

Read the source inventory and roadmap for details on open safety and compatibility work.

View source reference ↗Back to Kaze overview →