Pseudocode DSL

The sigMAX pseudocode DSL expresses business behavior within the Binary Contract’s inputs, outputs, primitive imports and capabilities. Its closed grammar gives the generation pipeline a form it can validate before producing executable source.

Active grammar: sigmax.pseudo/v0.3. Older v0.1 examples and instruction tables do not describe this Rust compiler.

Generation Stages

Generate · pseudocode.generate LLM compact pseudocode; deterministic parsing before persistence.
Parse · pseudocode.parse Revalidate compact source; produce expanded pseudocode and canonical AST.
Lower · source.generate Rust compiler generates C or MoonBit from the AST.
Compile · wasm.compile Compile the selected backend to WASM.
Record & verify · binary.agreement → binary.validate Record artifact evidence, then verify it against the contract.

A parser failure provides a precise diagnostic to the bounded repair attempt. Deterministic source generation has no API or LLM fallback.

Required Metadata

The parser expects the following metadata in order and checks it against the contract and primitive catalogue.

Prefix	Meaning
`#S`	Schema, currently `sigmax.pseudo/v0.3`.
`#M`	Contracted binary/module name.
`#F`	Contracted exported function and `i32` return type.
`#C`	Binary Contract path.
`#D`	Contracted route description.
`#V toon:`	Runtime catalogue name and version.

These values are checked, not accepted as free-form labels. The parser also validates input/output declarations, primitive availability and the semantic argument counts of calls.

Example

This example follows the compiler’s hash_body fixture. It requires the corresponding signed contract, route layout and permitted @sha512 primitive; it is not a standalone deployment manifest.

#S sigmax.pseudo/v0.3
#M hash_body
#F handle_hash_body -> i32
#C composant_checksum/contracts/binary/hash_body.contract.yaml
#D POST /hash
#V toon:sigmax-runtime-primitives@0.3.0
IN body body string RQ
OU sha string
CA @sha512(body) -> hash
IF KO hash
ER INVALID_BODY ST 400 ME "hash failed"
EN
EM sha = hash
RE OK

The handler reads a required body input, computes a bounded SHA-512 value, emits a declared error on failure and returns the structured sha output on success.

Form in this example	Meaning
`IN ... RQ`	Required declared input.
`OU`	Declared public output.
`CA @...`	Call a permitted semantic primitive.
`IF KO`	Branch on a failed result.
`ER ... ST ... ME ...`	Emit a named error with status and message.
`EM`	Emit the declared result.
`RE OK`	Successful completion.

This table explains the example rather than defining the complete grammar. The parser and catalogue determine which forms and primitives the active version accepts.

Semantic Calls And ABI Lowering

Pseudocode uses logical operations and values. It does not invent C pointers, output buffers or fixed capacities as extra primitive arguments. The compiler derives those details from the catalogue and generated types.

The same validated AST supports C and MoonBit. Their headers or libraries supply the bounded helpers, while host imports use the sigmax ABI. At the executable boundary, non-negative values represent successful primitive results and negative values represent errors; the generated code preserves the primitive-specific return meaning.

c_repr is the typed memory layout shared by generated code and the host. ObjectIR describes structured JSON output. DocIR describes document output rendered by the host. They serve different purposes and should not be substituted for one another.

Effects And Capabilities

Effect	Controlled path
Database operation	Logical binding, typed host invocation and storage service.
Outbound HTTP	Host primitive under the signed component’s outbound policy.
Events and blobs	Named route bindings and required capabilities.
Secrets and signatures	Host-managed secret or public-key references.
Logs, metrics and traces	Bounded runtime instrumentation primitives.

The runtime denies undeclared effects. An HTTP policy can use named destinations or explicitly permit dynamic origins with mode: all; neither option allows the module to open raw sockets. SQL stays in storage specifications and migrations.

Current Processing Limits

The catalogue and runtime define concrete resource bounds. Do not copy older 8 KiB HTTP/JSON limits into a new contract without checking the active implementation.

Resource	Current hard cap
Inbound JSON body, before and after decompression	1 MiB.
Request headers	32 KiB in aggregate.
Path and query	8 KiB.
Host-controlled outbound JSON	1 MiB.
Blob value passed through `blob.get` or `blob.put`	1 MiB.
Generic decompression output	4 MiB.
Regex input/output	8 KiB.
Random output	1 KiB.

Routes can lower inbound HTTP limits. Large data should use bounded pagination or a host-mediated object-storage transfer rather than oversized guest buffers. Buffer allocation and cleanup remain compiler responsibilities.

Streaming primitives are deferred in the current ABI until backpressure, cancellation and queued-byte bounds are implemented.

Execution And Evidence

The DSL remains contract-first across both proprietary editions. Core executes WASM inside its runtime container. Pro uses COS2000 inside a KubeVirt VM; supported imports and ABI compatibility must be validated for that executor.

Generation traces and agreements connect the original contract, chosen model, compact source, canonical AST, generated source and compiled binary. An unmapped natural-language acceptance criterion remains pending rather than being marked passed by inference.

The implementation references are studio/tools/pseudocode-compiler/src/parser.rs, src/codegen.rs, tests/pipeline.rs and runtime/functions.toon in sigMAX_runtime.