Decode JSON into a refined record

Generated by cargo run -p agent_docs from compiler/examples/. Edit the example files, then regenerate.

Decode an order once and let its field refinements reject invalid external data.

Json.decode infers Order from the return annotation and checks both the record shape and the predicates on item and quantity. Its Result keeps malformed JSON, missing fields and invalid quantities recoverable; main handles both branches and reports the decoding path. Use from only for trusted values where a failed predicate should be a defect. No permissions are needed.

The harness runs main (expecting 2 x tea) and both tests. The tests cover a valid record, invalid JSON, an empty name, missing quantity and both out-of-range bounds.

Source project · harness mode: run + test.

From the repository root, with this checkout's sakura on PATH:

cd compiler/examples/json_refined
sakura check --json
sakura run
sakura test --json

Manifest and permissionsCopy Anchor Link

[package]
name = "json_refined"
version = "0.1.0"
edition = "2026"

[permissions]

Source and testsCopy Anchor Link

src/main.sakura includes all required imports and tests.

// milestone: M3
// mode: run
// spec: design §17.145

import std/json.{DecodeError}

type Quantity = Int where it >= 1 && it <= 100
type Order = { item: String where String.len(it) > 0, quantity: Quantity }

fn read_order(text: String) -> Result<Order, DecodeError> { Json.decode(text) }

pub fn main() -> Unit ! {Console} {
  match read_order("\{\"item\":\"tea\",\"quantity\":2\}") {
    Ok(order) => Console.print("{order.quantity} x {order.item}"),
    Err(err) => Console.print("invalid order at {err.path}: {err.message}"),
  }
}

test "JSON decoding validates the record fields" {
  expect_eq(
    read_order("\{\"item\":\"tea\",\"quantity\":2\}"),
    Ok(Order { item: "tea", quantity: 2 }),
  )
}

test "malformed JSON and invalid fields are recoverable" {
  expect(Result.is_err(read_order("not json")))
  expect(Result.is_err(read_order("\{\"item\":\"tea\",\"quantity\":0\}")))
  expect(Result.is_err(read_order("\{\"item\":\"tea\",\"quantity\":101\}")))
  expect(Result.is_err(read_order("\{\"item\":\"\",\"quantity\":1\}")))
  expect(Result.is_err(read_order("\{\"item\":\"tea\"\}")))
}

Expected stdoutCopy Anchor Link

2 x tea

Compiler provenance and regenerationCopy Anchor Link

These eight projects teach supported Sakura APIs on the JavaScript backend. Each project is exercised offline by cargo test -p sakura_cli --test examples; HTTP and LLM exchanges are synthetic committed cassettes, with no network or API keys. Use Node 26 for execution, including its built-in SQLite implementation.

The initial API baseline is compiler revision 5cae349516c21714d90d36e87f1cfd6debe980c6. CI reruns these projects against the compiler in the same checkout. Build that checkout's CLI and run sakura --version and sakura prompt before adapting a recipe; pre-alpha APIs can change. An installed skill's frontmatter records its compiler version and build revision. These teaching examples are separate from the agent evaluation tasks.

The source of each page is its example's recipe.md, sakura.toml, src/main.sakura and fixture files. Run cargo run -p agent_docs from compiler/ to regenerate the cookbook and skill reference. Edit those sources, not the rendered pages.