1.11.7.1 controlled concurrency and atomicity

This release fixes resource lifetimes and delivers seven experimental APIs, disabled by default. Review state ownership, cooperative file locks, strict transactions and bounded-task guarantees before enabling them.

Read the complete guide and examples
Includes the guarantee matrix, failure handling and actual validation evidence
/en/learn/concurrency-scopes

1.2HHY 1.7.1 implementation and compatibility

1.7.1 passes local tests, four-platform CI and release validation. Language specification 1.0 remains frozen. Official sample, HTML and macOS/Linux Database 1.0.0 extensions are verified compatible. VS Code 0.2.0 and Sublime 0.1.0 retain independent versions; syntax and editor contract checks pass.

HIR, six optimization passes, integer MIR, type-feedback guards/deopt and local List scalar replacement are implemented. Explicitly enable HHY_COMPILER=ir, HHY_FEEDBACK_SPECIALIZATION=1 and HHY_SCALAR_REPLACEMENT=1; direct Bytecode remains default. Real workloads have not met default-enablement benefit gates. Scalar replacement retains original GC/quota reservations.

Optimization switches, verification and supported scope
v1.7.1 implementation
/docs/COMPILER_IR.md

1.7.1 release notes
Released capabilities and limits
/docs/RELEASE_NOTES_1.7.1.md

1.3Minute 1: one-command install (recommended)

The installer supports macOS arm64, Linux x86_64, and Linux arm64. It detects the platform, downloads the V1.7.1 archive and matching .sha256, and installs only after verification. sudo is not required by default.

curl -fsSL https://hhylang.dev/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"
hhy --version

1.4macOS: install from the Homebrew tap

Apple Silicon Macs can use the Formula maintained in this repository. The explicit Git URL lets the repository act as a tap before a separate homebrew-tap repository is created.

brew tap hh696-wq/hhy https://github.com/hh696-wq/hhy-vm.git
brew install hhy
hhy --version

1.5Option 2: download a Release

If you are not modifying the HHY Runtime, an official V1.7.1 archive is the fastest path. Choose darwin-arm64, linux-x86_64, or linux-arm64 for your OS and CPU. Archives include the executable, official sample and database extensions, required non-system runtime libraries, docs, licenses, and build metadata.

Open HHY GitHub Releases ↗
Download the latest stable archive and its matching .sha256 file or SHA256SUMS.
https://github.com/hh696-wq/hhy-vm/releases

tar -xzf hhy-1.7.1-PLATFORM-ARCH.tar.gz
cd hhy-1.7.1-PLATFORM-ARCH
./bin/hhy --version
./bin/hhy run examples/07-language-basics.hhy

1.6Verify the download and add it to PATH

Before running a download, verify it with the matching .sha256 file or SHA256SUMS. macOS includes shasum; Linux commonly provides sha256sum.

# macOS
shasum -a 256 -c hhy-1.7.1-darwin-arm64.tar.gz.sha256

# Linux
sha256sum -c hhy-1.7.1-linux-x86_64.tar.gz.sha256

# Add to PATH for this terminal (use the real absolute path)
export PATH="/absolute/path/hhy-1.7.1-PLATFORM-ARCH/bin:$PATH"
hhy --version

For permanent access, put the export PATH line in your shell profile. You may also keep invoking ./bin/hhy from the extracted directory without a system-wide install.

1.7Option 3: build from source

Build from source when developing the Runtime, validating current source, or choosing a custom installation prefix. HHY V1.7.1 supports macOS arm64, Linux arm64, and Linux x86_64 and requires a C11 compiler, make, libcurl, PCRE2, and BDWGC. The database extension additionally needs the corresponding PostgreSQL libpq or MySQL client development library.

brew install curl pcre2 bdw-gc jansson openssl@3 zlib
git clone https://github.com/hh696-wq/hhy-vm.git
cd hhy-vm
make
make test
./build/hhy --version

1.8Install the source build

make install PREFIX="$(brew --prefix)"
hhy --version

PREFIX may be a custom absolute path. Once PREFIX/bin is on PATH, execute any .hhy file with hhy run.

1.9Your first script

let language = "HHY"

["Flow", "Pipe", "System"]
    |> stream
    |> map { word -> language + ": " + word }
    |> print

hhy check hello.hhy
hhy run hello.hhy

let creates a binding; the List literal stores three Strings; stream explicitly converts it into a Stream; |> injects the left value into the next call; the map closure creates one new String per item; print consumes the result. check validates lexical syntax, scope, modules, and known standard-library calls without effects.

1.10Running scripts and the development workflow

HHY source files use the .hhy suffix. View complete command help:

hhy --help

2.1What dynamic typing means

HHY declarations omit types; each value carries its logical type at runtime. Dynamic does not mean coercive: conditions require Bool, String never automatically becomes Number, Bool, or Path, and invalid arity or operations raise structured errors. Use type(value) to inspect a type and is_type(value, name) to test it.

let nothing = null
let enabled = true
let count = 42
let ratio = 0.75
let title = "HHY"
let pattern = /ERROR|WARN/i
let names = ["Ada", "Linus"]
let user = { name: "Ada", active: true }
let indexes = 0..3
let size_limit = 10mib
let timeout_limit = 5s
let completion = 80%

print(type(user))
print(is_type(title, "String"))

2.2Scalar and unit types

Precise String, number, unit, and Path edge cases belong in Reference. For ordinary scripts, remember that HHY never implicitly converts among String, Number, Bool, and Path.

Open the type and syntax reference →
Look up exact UTF-8, overflow, operator, and literal behavior.
/en/learn/syntax-reference

2.3List, Map, and Range

List indices start at zero and out-of-range access raises IndexError. Map keys are Strings and preserve insertion order; map.key equals map["key"]. A missing key normally returns null, while require distinguishes a missing key from a present key whose value is null. Range a..b includes a and excludes b without allocating a List.

let original = ["Flow", "System"]
let extended = append(original, "Pipe")
let shortened = remove_at(extended, 1)

let config = { retries: 3, label: null }
let updated = put(config, "timeout", 5s)
let selected = pick(updated, ["retries", "timeout"])

print(original)
print(shortened)
print(get(config, "missing"))
print(require(config, "label"))
print(selected)

Lists and Maps are not mutated in place. append, remove_at, put, remove_key, and pick return new collections, leaving original and config unchanged. Lists and Maps support deep equality; Functions, Streams, and system resources do not support value equality.

2.4Result, Stream, and system objects

System objects are not Maps. Map or pick ordinary fields before JSON encoding. Flow explains Stream laziness and consumption in detail.

2.5Bindings, scope, and immutability

let service = "api"
let mut retries = 0
retries = retries + 1

let creates a binding that cannot be reassigned; use let mut when reassignment is required. List and Map update functions return new collections rather than mutating originals. Names follow block lexical scope and must be declared before use.

2.6Conditions, loops, and functions

fn classify(score) {
    if score >= 90 { return "excellent" }
    else if score >= 60 { return "pass" }
    else { return "retry" }
}

let mut total = 0
for score in [98, 72, 55] {
    if score < 60 { continue }
    total = total + score
}

let mut attempts = 0
while attempts < 3 {
    attempts = attempts + 1
}

print(classify(98))
print(total)

HHY supports if / else if / else, for item in iterable, while, break, and continue. for iterates Lists, Map entries, Ranges, or Streams; iterating a Stream consumes it. Functions use positional arguments checked at call time and return null without an explicit return.

fn summarize(items) {
    let mut total = 0

    for item in items {
        if item.enabled {
            total = total + item.score
        }
    }

    return total
}

let users = [
    { name: "Ada", enabled: true, score: 98 },
    { name: "Linus", enabled: false, score: 86 }
]

summarize(users) |> print

In the current 1.7.1 runtime, use the trailing Flow closure form { item -> expression }; a multi-statement closure must name its parameter and use return. A one-argument closure in an unambiguous Flow context may use { it * 2 }. V1.7.1 has no overloading, generics, or default arguments.

3.1How Pipe passes values

Pipe is a composition rule for ordinary calls: x |> f means f(x), x |> f(a) means f(x, a), and x |> obj.f(a) means obj.f(x, a). It does not turn scalars into Streams, flatten nested Streams, access it fields, ignore errors, stringify values, or invoke a shell.

[1, 2, 3, 4, 5]
    |> stream
    |> map { number -> number * 2 }
    |> where { number -> number > 5 }
    |> take(2)
    |> print

3.2Stream lifecycle

A Stream is a lazy, pull-based, single-consumption sequence. Building a pipeline only composes operators; upstream produces items when a terminal starts pulling. Its lifecycle is open → next* → close, and normal completion, early take, errors, and cancellation all close resources upstream.

3.3Item, filter, and observation operators

[5, 2, 5, 1, 3]
    |> stream
    |> skip(1)
    |> take(4)
    |> inspect { number -> print("seen", number) }
    |> where { number -> number >= 3 }
    |> map { number -> number * 10 }
    |> distinct
    |> collect
    |> print

map(Stream<T>, Function(T -> U)) -> Stream<U>

where(Stream<T>, Function(T -> Bool)) -> Stream<T>

take(Stream<T>, Int) -> Stream<T>

skip(Stream<T>, Int) -> Stream<T>

inspect(Stream<T>, Function(T -> Value)) -> Stream<T>

distinct(Stream<Hashable>) -> Stream<Hashable>

3.4map versus flat_map

map sends exactly the closure result downstream. Returning a Stream therefore creates Stream<Stream<T>>. flat_map requires a Stream result and concatenates each child stream into one Stream.

let batches = [[1, 2], [3, 4]]

batches
    |> stream
    |> flat_map { batch -> batch |> stream }
    |> print

3.5What barriers and terminals actually do

Item operators retain only the current item. A barrier must inspect or retain substantial input before producing a correct result: sort_by stores all input before sorting, group_by stores every group's values, collect builds a List, and terminals such as reduce/count/sum read to completion before returning a scalar. All obey memory, collection-size, and runtime limits.

let ordered = [5, 1, 3, 2, 4]
    |> stream
    |> sort_by({ order: "asc" }) { number -> number }
    |> collect

let grouped = [
    { team: "core", name: "Ada" },
    { team: "web", name: "Linus" },
    { team: "core", name: "Grace" }
]
    |> stream
    |> group_by { person -> person.team }
    |> collect

print(ordered)
print(grouped)

sort_by(Stream<T>, Map, Function(T -> Comparable)) -> Stream<T>

group_by(Stream<T>, Function(T -> Hashable)) -> Stream<Group<T>>

collect(Stream<T>) -> List<T>

reduce(Stream<T>, U, Function(State<T,U> -> U)) -> U

count(Stream<T>) -> Int

sum(Stream<Number>) -> Number

min(Stream<Number>) -> Number | Null

max(Stream<Number>) -> Number | Null

first(Stream<T>) -> T | Null

last(Stream<T>) -> T | Null

any(Stream<T>, Function(T -> Bool)) -> Bool

all(Stream<T>, Function(T -> Bool)) -> Bool

3.6Effects, errors, and parallelism

Only a terminal or Action consumes a Pipeline. print, for_each, save_*, run, and send perform output, filesystem, process, or network work. Ordinary Errors terminate the Pipeline; use attempt for per-item Results and on_error to replace a failed upstream Stream.

parallel(n) uses isolated workers and preserves output order. Parallel and Watch covers concurrency limits, Sendable values, and cancellation.

4.11.7.1 controlled concurrency and atomicity

This release fixes resource lifetimes and delivers seven experimental APIs, disabled by default. Review state ownership, cooperative file locks, strict transactions and bounded-task guarantees before enabling them.

Read the complete guide and examples
Includes the guarantee matrix, failure handling and actual validation evidence
/en/learn/concurrency-scopes

4.2Path is not String

Every filesystem API requires Path. path(text) normalizes lexically: it collapses repeated separators and ., and resolves removable .. segments without accessing the filesystem or resolving symlinks. A relative Path is always based on the process startup directory, not the importing file.

let source = path("./src/../src/main.c")
let target = path_join(source.parent, "runtime.c")

print(source)
print(source.name)
print(source.extension)
print(source.parent)
print(target)

name, extension, and parent are read-only Path fields—not path_name(), path_extension(), or path_parent() functions. extension includes the leading dot and is empty when absent; path_join(base, child) returns a new combined Path.

4.3files: traversal, globs, and metadata

path("./logs")
    |> files("**/*.log")
    |> where { file -> file.size > 1mib }
    |> flat_map { file -> read_lines(file.path) }
    |> where { line -> contains(line, "ERROR") }
    |> save_lines(path("errors.txt"))

files(root, pattern, options?) returns a lazy Stream<File | Directory> and excludes the traversal root itself. Patterns support *, ?, and **. Directory symlinks are not followed by default; { follow_symlinks: true } opts in with cycle detection.

File and Directory are system objects, not Maps. Map required fields into an ordinary Map before JSON encoding.

4.4Reading text and binary data

read_text(Path) -> String

read_lines(Path) -> Stream<String>

read_bytes(Path) -> BytesBuffer

4.5Writing, appending, and atomic saves

let input = path("notes.txt")
let backup = path("backup-notes.txt")

write_text(input, "first line\n", { overwrite: true })
append_text(input, "second line\n")
copy(input, backup, { overwrite: false })

read_lines(backup)
    |> map { line -> upper(line) }
    |> save_lines(path("backup/upper.txt"), { create_parents: true })

write_text(Path, String, Map?) -> Path

append_text(Path, String) -> Path

write_bytes(Path, BytesBuffer, Map?) -> Path

save_text(String | Stream<String>, Path, Map?) -> Path

save_lines(Stream<String>, Path, Map?) -> Path

write_text, write_bytes, save_text, and save_lines accept overwrite (default true) and create_parents (default false). They commit through a same-directory temporary file plus rename; overwrite: false uses atomic no-replace to prevent check-then-write races.

4.6Copy, move, remove, and dry-run

copy(Path, Path, Map?) -> Path

move(Path, Path, Map?) -> Path

remove(Path) -> Path

hhy run --dry-run backup.hhy
hhy run backup.hhy

The target parent directory for copy and move must already exist; the current 1.7.1 runtime does not process their create_parents option. The example uses overwrite: false; choose a new backup filename before repeating it. Review the dry-run plan before executing a script that copies, moves, or removes files.

4.7Look up the complete API

Paths and files API Reference →
Look up every signature, parameter form, and stable function anchor.
/en/learn/standard-library#fn-path

5.1String and UTF-8

String is an immutable UTF-8 byte sequence. length counts Unicode code points, byte_length counts encoded bytes, and indexing returns a one-code-point String. Text functions return new values and never mutate the original.

let line = "  ERROR: timeout  "

line
    |> trim
    |> replace("ERROR", "WARN")
    |> lower
    |> print

trim(String) -> String

split(String, String) -> List<String>

join(List<String>, String) -> String

replace(String, String, String) -> String

contains(String | List, Value) -> Bool

starts_with(String, String) -> Bool

ends_with(String, String) -> Bool

lower(String) -> String

upper(String) -> String

5.2Regex

A Regex literal is /pattern/flags with i (case-insensitive), m (multiline), s (dot matches newline), and u. regex_match returns Bool; regex_captures returns the full match, byte positions, numbered groups, and named captures, or null when unmatched.

5.3JSON type mapping and errors

read_text(path("users.json"))
    |> parse_json
    |> get("users")
    |> stream
    |> where { user -> user.active == true }
    |> collect
    |> encode_json({ pretty: true })
    |> save_text(path("active-users.json"))

parse_json reports line and column on failure. encode_json accepts { pretty: true } for readable output. Function, Stream, and system objects require mapping to ordinary fields first.

5.4CSV is a record stream

parse_csv accepts a complete String or Stream<String> and returns Stream<Map>; encode_csv accepts Stream<Map> and returns Stream<String> records without terminators. Neither requires a whole-file buffer.

read_lines(path("employees.csv"))
    |> parse_csv({ header: true })
    |> where { row -> row.active == "true" }
    |> encode_csv({ header: true })
    |> save_lines(path("active-employees.csv"))

header controls field names; delimiter and quote must be single characters. CSV performs no schema inference, so numbers and Bools require explicit conversion. encode_csv omits terminators and composes with save_lines.

5.5Look up the complete API

Text and structured data API Reference →
Look up complete signatures for text, Regex, JSON, and CSV functions.
/en/learn/standard-library#fn-contains

6.1The safety boundary between run and shell

run(["git", "log", "--oneline"], { timeout: 5s })
    |> stdout_lines
    |> take(10)
    |> print

run(argv, options?) passes List<String> directly to the OS without a shell, so spaces, globs, $, redirects, and pipes are not reinterpreted. Use shell(command, options?) only when shell syntax is intentional; the Checker emits a safety hint.

6.2CommandResult

run and shell wait by default and return CommandResult. A nonzero child exit code is not automatically an HHY Error; inspect exit_code for business success.

A nonzero exit_code does not automatically become an HHY Error; interpret it according to the command. stdout_lines(result) exposes captured output as a line Stream.

6.3Process snapshots and fields

processes() returns a current Stream<Process> snapshot. Process is not a Map and exposes read-only pid, name, cpu, memory, status, and command fields. Explicitly map ordinary fields before JSON encoding.

6.4args, env, system, and stdin

if length(args) != 1 {
    print_error("usage: script.hhy <input>")
    exit(3)
}

let input = path(args[0])

6.5Look up the complete API

Processes and system API Reference →
Look up complete signatures for run, shell, processes, stdin_lines, and every.
/en/learn/standard-library#fn-run

7.1Request → Policy → Send → Response

http.get("https://example.com/users")
    |> timeout(5s)
    |> retry({ count: 3, backoff: 200ms })
    |> send
    |> response_body
    |> parse_json
    |> print

http.get/post/put/delete(url, options?) only build immutable HttpRequests without network access. timeout(request, duration) and retry(request, options) return new policy-adjusted Requests; send(request) performs the network effect and returns HttpResponse. Dry-run can therefore inspect the full plan without execution.

7.2Request options and safe defaults

TLS verification is enabled by default. Sensitive Authorization and Cookie headers are redacted in plans, logs, and Errors. Response bodies obey max_http_body.

7.3Timeout, retries, and idempotency

retry({ count, backoff }) defaults to connection errors, timeouts, 429, and selected 5xx statuses. GET, PUT, and DELETE may retry by policy; POST does not retry automatically to avoid duplicate creation or charges. Timeout and Ctrl+C cancel libcurl work and release response resources.

7.4HttpResponse and response bodies

send returns an in-memory HttpResponse. Use response_body for UTF-8 text and response_bytes for binary data; send_to(request, path) writes directly from curl into a sibling temporary file and atomically publishes it, returning only path and size.

http.get("https://api.example.com/status")
    |> timeout(3s)
    |> send
    |> response_body
    |> parse_json
    |> print

7.5Look up the complete API

HTTP API Reference →
Look up request builders, timeout, retry, send, and response readers.
/en/learn/standard-library#fn-http-get

8.11.7.1 controlled concurrency and atomicity

This release fixes resource lifetimes and delivers seven experimental APIs, disabled by default. Review state ownership, cooperative file locks, strict transactions and bounded-task guarantees before enabling them.

Read the complete guide and examples
Includes the guarantee matrix, failure handling and actual validation evidence
/en/learn/concurrency-scopes

8.2parallel is a bounded concurrent map

let urls = [
    "https://example.com",
    "https://example.org"
]

urls
    |> stream
    |> parallel(2) { url ->
    http.get(url)
        |> timeout(5s)
        |> send
}
    |> print

If a closure returns Stream, apply flat_map after parallel. Dry-run creates no workers but still checks closure Effects in order.

8.3Sendable values and isolation

Workers receive frozen snapshots of input and captured values, never shared mutable objects. Null, Bool, numbers, String, units, Path, and ordinary Lists/Maps/system snapshots whose fields are sendable can be copied.

8.4watch and FileEvent

watch(path("./src"))
    |> where { event -> event.kind == "created" or event.kind == "modified" }
    |> debounce(300ms)
    |> for_each { event ->
    print(event.path)
}

watch(path, { recursive? }) returns an infinite Stream<FileEvent>. FileEvent exposes read-only kind, path, old_path, and timestamp; kind is created, modified, removed, or renamed, and old_path exists only for renamed. Event sequences vary by platform and editor; first create a file in a test directory to verify the watcher, then check modification and rename behavior.

watch is an infinite Stream. End it with Ctrl+C, timeout, or cancel. Recursive watch obeys max_open_files, and filesystems may merge rapid duplicate events.

8.5debounce and every

debounce(window) is leading-edge: the first scalar or kind + path FileEvent emits immediately; duplicates inside the window are coalesced and reset the window. Different event keys do not block each other.

every(duration) returns an infinite tick Stream. If downstream is busy, backpressure prevents overlapping the same tick. Apply take or a business window before collect/sort/group.

8.6Cancellation and cleanup

Ctrl+C, timeout, cancel(), and unhandled errors trigger one root CancellationToken. Watchers, sleep, HTTP, child processes, and workers poll it; cancellation closes queues and handles, terminates children, and propagates Stream close upstream.

9.1Import forms and path resolution

import { add } from "./math.hhy"

add(20, 22) |> print

Relative paths resolve from the current source file. Standard modules use bare names; local files explicitly use ./, ../, or an absolute Path.

9.2Exports, scope, and execution

export let version = "1.0"

export fn normalize_name(name) {
    return name |> trim |> lower
}

fn internal_helper() {
    return null
}

Only exported names are visible to importers. A module owns its top-level scope, executes once on first import, and is then cached. Import cycles raise CheckError before execution. V1.7.1 supports standard and local modules plus process-extension modules installed from local packages.

9.3Error fields and categories

Every failure uses Error rather than null or printed text. Error exposes kind, code, message, source, stage, cause, stack, and context. Sensitive headers, credentials, and full file contents are excluded from context by default.

Built-in categories include SyntaxError, CheckError, TypeError, ValueError, IndexError, KeyError, EncodingError, IoError, ProcessError, HttpError, HttpStatusError, TimeoutError, CancelledError, ResourceLimitError, and PlanError.

9.4try/catch and rethrowing

try {
    read_text(path("config.json"))
        |> parse_json
        |> print
} catch err {
    print_error(err)
    exit(1)
}

catch receives the first Error propagated from try. Execution continues after a normally completed catch; use throw(err) to preserve the error chain when it cannot be handled. An unhandled Error exits nonzero.

9.5Flow errors and per-item Result

path("./configs")
    |> files("**/*.json")
    |> map { file -> attempt { read_text(file.path) } }
    |> where { result -> result.ok }
    |> map { result -> result.value }
    |> print

An unhandled Error in a Stream terminates the Pipeline. attempt converts one operation to Result for batches that explicitly retain successes and failures. on_error replaces an entirely failed upstream Stream and never silently skips an item.

9.6Resource cleanup guarantees

Error, return, exit, timeout, Ctrl+C, and cancel share one unwind path. Stream close is idempotent; failed atomic saves delete temporary files and preserve the old file; child processes, HTTP responses, watchers, and workers respond to cancellation.

10.1Hello HHY and Flow

The smallest runnable example: turn a List into a Stream, map and filter values, then print the result. Corresponds to examples/00-hello.hhy.

let language = "HHY"

["Flow", "Pipe", "System"]
    |> stream
    |> map { word -> language + ": " + word }
    |> print

HHY: Flow
HHY: Pipe
HHY: System

✓ exit 0 · Flow pipeline completed

10.2Extract log alerts concurrently

Recursively scan large log files with four workers, extract ERROR/WARN lines, and retain each source path. Useful for incident response and scheduled log jobs.

if length(args) != 2 {
    print_error("usage: hhy run log-errors.hhy <log-dir> <output-file>")
    exit(3)
}

let log_dir = path(args[0])
let output_file = path(args[1])

log_dir
    |> files("**/*.log")
    |> where { file -> file.size > 1mib }
    |> parallel(4) { file ->
    read_lines(file.path)
        |> where { line -> regex_match(line, /ERROR|WARN/) }
        |> map { line -> encode_json(file.path) + ": " + line }
        |> collect
}
    |> flat_map { lines -> lines |> stream }
    |> save_lines(output_file)
    |> on_error { err ->
    print_error(err)
    throw(err)
}

hhy run log-errors.hhy ./logs ./output/errors.txt

logs/api.log: 2026-08-25T09:18:42Z ERROR database timeout after 3000ms
logs/worker.log: 2026-08-25T09:18:44Z WARN retrying job #1842
logs/api.log: 2026-08-25T09:18:47Z ERROR upstream returned 502

✓ exit 0 · 3 alerts written to output/errors.txt

10.3Sync active users from an API

Fetch users with timeout and retry, parse JSON, select fields, and atomically save only active users. Corresponds to examples/02-active-users.hhy.

if length(args) != 2 {
    print_error("usage: hhy run active-users.hhy <url> <output-file>")
    exit(3)
}

http.get(args[0])
    |> timeout(5s)
    |> retry({ count: 3, backoff: 200ms })
    |> send
    |> response_body
    |> parse_json
    |> get("users")
    |> stream
    |> where { user -> user.active == true }
    |> map { user ->
    { id: user.id, name: user.name, email: user.email }
}
    |> collect
    |> encode_json({ pretty: true })
    |> save_text(path(args[1]))
    |> on_error { err ->
    print_error(err)
    throw(err)
}

hhy run active-users.hhy https://api.example.com/users active-users.json

[
  { "id": 101, "name": "Ada", "email": "ada@example.com" },
  { "id": 108, "name": "Linus", "email": "linus@example.com" }
]

✓ exit 0 · 2 active users written to active-users.json

10.4Monitor process CPU and memory

Sample processes every five seconds, keep CPU-heavy or memory-heavy entries, and print the top ten by memory. Corresponds to examples/03-process-monitor.hhy.

every(5s)
    |> for_each { tick ->
    processes
        |> where { process ->
        process.cpu > 70% or process.memory > 1gib
    }
        |> sort_by({ order: "desc" }) { process -> process.memory }
        |> take(10)
        |> map { process ->
        {
            pid: process.pid,
            name: process.name,
            cpu: process.cpu,
            memory: process.memory
        }
    }
        |> print
}

[{ pid: 8421, name: "node", cpu: 82.4%, memory: 1.42 GiB },
 { pid: 9107, name: "hhy",  cpu: 74.1%, memory: 86.3 MiB }]

next sample in 5s… · Ctrl+C exits safely

10.5Check service health in batches

Probe multiple services concurrently with consistent timeouts and retries. A failed endpoint is recorded without terminating the whole batch.

let services = [
    { name: "users", url: "https://api.example.com/users/health" },
    { name: "orders", url: "https://api.example.com/orders/health" },
    { name: "billing", url: "https://api.example.com/billing/health" }
]

services
    |> stream
    |> parallel(3) { service ->
    let response = attempt {
        http.get(service.url)
            |> timeout(3s)
            |> retry({ count: 2, backoff: 100ms })
            |> send
            |> response_body
            |> parse_json
    }

    let mut status = "unreachable"
    let mut error_message = null

    if response.ok {
        status = response.value.status
    } else {
        error_message = response.error.message
    }

    return {
        name: service.name,
        ok: response.ok,
        status: status,
        error: error_message
    }
}
    |> collect
    |> encode_json({ pretty: true })
    |> print

[
  { "name": "users",   "ok": true,  "status": "healthy", "error": null },
  { "name": "orders",  "ok": true,  "status": "healthy", "error": null },
  { "name": "billing", "ok": false, "status": "unreachable", "error": "request timed out" }
]

✓ exit 0 · all 3 checks completed despite one endpoint failure

10.6Release quality gate

Run tests, lint, and production builds in parallel, save a machine-readable report, and block a release with a stable exit code when any check fails.

let checks = [
    { name: "unit-tests", command: ["make", "test"] },
    { name: "lint", command: ["npm", "run", "lint"] },
    { name: "production-build", command: ["npm", "run", "build"] }
]

let report = checks
    |> stream
    |> parallel(3) { check ->
    let result = run(check.command, { timeout: 10min, max_output: 8mib })
    return {
        name: check.name,
        passed: result.exit_code == 0,
        exit_code: result.exit_code,
        output: result.stdout
    }
}
    |> collect

report |> encode_json({ pretty: true }) |> save_text(path("release-gate.json"))

if report |> stream |> any { check -> check.passed == false } {
    print_error("release blocked: one or more checks failed")
    exit(1)
}

print("release gate passed")

unit-tests       PASS  4.28s
lint             PASS  1.14s
production-build PASS  6.72s
release-gate.json written

✓ exit 0 · release gate passed

10.7Source secret audit

Scan configuration and source files concurrently for suspected API keys, passwords, and private keys, then produce a security review report.

if length(args) != 2 {
    print_error("usage: hhy run secret-audit.hhy <source-dir> <report-file>")
    exit(3)
}

path(args[0])
    |> files("**/*")
    |> where { file ->
    file.extension == ".env" or
    file.extension == ".yml" or
    file.extension == ".json" or
    file.extension == ".ts"
}
    |> parallel(4) { file ->
    read_lines(file.path)
        |> where { line ->
        regex_match(line, /API_KEY|SECRET|PASSWORD|BEGIN PRIVATE KEY/)
    }
        |> map { line -> encode_json(file.path) + ": " + line }
        |> collect
}
    |> flat_map { matches -> matches |> stream }
    |> save_lines(path(args[1]))

services/billing/.env: PAYMENT_API_KEY=***
services/auth/config.yml: PASSWORD: ***

✓ exit 0 · 2 suspected secrets require review

10.8Order and payment reconciliation

Merge order and payment CSV files into one flow, group records by order_id, and report missing records or mismatched amounts.

if length(args) != 3 {
    print_error("usage: hhy run reconcile.hhy <orders.csv> <payments.csv> <report.json>")
    exit(3)
}

[path(args[0]), path(args[1])]
    |> stream
    |> flat_map { input ->
    read_lines(input) |> parse_csv({ header: true })
}
    |> group_by { record -> record.order_id }
    |> where { group ->
    (group.values |> stream |> count) != 2 or
    (group.values |> stream |> map { record -> record.amount } |> distinct |> count) != 1
}
    |> map { group ->
    { order_id: group.key, records: group.values, issue: "missing_or_amount_mismatch" }
}
    |> collect
    |> encode_json({ pretty: true })
    |> save_text(path(args[2]))

orders: 12,480 · payments: 12,472
matched: 12,461
exceptions: 19 → exceptions.json

✓ exit 0 · reconciliation report written atomically

10.9Multi-tenant usage snapshot

Fetch tenant usage with bounded concurrency, consistent retries, and failure isolation. Useful for billing, capacity analysis, and customer success reports.

let tenants = [
    { id: "acme", url: "https://api.example.com/acme/usage" },
    { id: "nova", url: "https://api.example.com/nova/usage" },
    { id: "orbit", url: "https://api.example.com/orbit/usage" }
]

tenants
    |> stream
    |> parallel(3) { tenant ->
    let result = attempt {
        http.get(tenant.url)
            |> timeout(5s)
            |> retry({ count: 3, backoff: 200ms })
            |> send
            |> response_body
            |> parse_json
    }

    if result.ok {
        return { tenant: tenant.id, ok: true, usage: result.value, error: null }
    }

    return { tenant: tenant.id, ok: false, usage: null, error: result.error.message }
}
    |> collect
    |> encode_json({ pretty: true })
    |> save_text(path("tenant-usage-snapshot.json"))

acme  ✓ requests=184203 storage_gb=82.4
nova  ✓ requests=99102  storage_gb=41.8
orbit ✗ request timed out

✓ exit 0 · snapshot contains both data and failure reasons

10.10Oversized asset governance

Find large image and video assets, sort them by size, and produce a JSON inventory for compression or storage migration work.

if length(args) != 2 {
    print_error("usage: hhy run asset-audit.hhy <asset-dir> <report.json>")
    exit(3)
}

path(args[0])
    |> files("**/*")
    |> where { file ->
    file.is_file and
    (file.extension == ".png" or file.extension == ".jpg" or file.extension == ".mp4")
}
    |> where { file -> file.size > 5mib }
    |> sort_by({ order: "desc" }) { file -> file.size }
    |> map { file ->
    { path: file.path, bytes: file.size, extension: file.extension }
}
    |> collect
    |> encode_json({ pretty: true })
    |> save_text(path(args[1]))

scanned 1,842 assets
large assets: 27
largest: public/video/launch.mp4 · 184.2 MiB

✓ exit 0 · asset-report.json generated

10.11Watch sources and rebuild

Watch C sources, debounce rapid saves, and run make. Build failures are reported while the watcher stays alive.

if length(args) != 1 {
    print_error("usage: hhy run watch-build.hhy <source-dir>")
    exit(3)
}

let source_dir = path(args[0])

watch(source_dir, { recursive: true })
    |> where { event ->
    event.kind != "removed" and
    (event.path.extension == ".c" or event.path.extension == ".h")
}
    |> debounce(300ms)
    |> for_each { event ->
    print("changed:", event.path)

    let result = run(["make"], { timeout: 2min, cwd: system.cwd })

    if result.exit_code != 0 {
        print_error(result.stderr)
    } else {
        print(result.stdout)
    }
}

hhy run watch-build.hhy ./src

watching ./src recursively…
changed: src/runtime/flow.c
cc -std=c11 -O2 -c src/runtime/flow.c
cc build/*.o -lcurl -lpcre2-8 -lgc -o build/hhy
Build complete: build/hhy

✓ watcher remains active · waiting for the next change

10.12Build a department report from CSV

Read employee CSV records, keep active employees, aggregate headcount and salary by department, and atomically save formatted JSON.

if length(args) != 2 {
    print_error("usage: hhy run csv-report.hhy <input.csv> <output.json>")
    exit(3)
}

read_lines(path(args[0]))
    |> parse_csv({ header: true })
    |> where { employee -> employee.active == "true" }
    |> group_by { employee -> employee.department }
    |> map { group ->
    {
        department: group.key,
        employees: group.values |> stream |> count,
        total_salary: group.values
            |> stream
            |> map { employee -> employee.salary |> to_float }
            |> sum
    }
}
    |> collect
    |> encode_json({ pretty: true })
    |> save_text(path(args[1]))

hhy run csv-report.hhy employees.csv department-report.json

[
  { "department": "Engineering", "employees": 12, "total_salary": 2160000 },
  { "department": "Product", "employees": 5, "total_salary": 810000 }
]

✓ exit 0 · department-report.json written atomically

10.13Back up large files with dry-run

Create the backup directory first (for example, mkdir -p ./backup). Find files over 100 MiB and copy them into that directory. Inspect the plan with dry-run before performing real writes.

if length(args) != 2 {
    print_error("usage: hhy run backup-large.hhy <source-dir> <backup-dir>")
    exit(3)
}

let source_dir = path(args[0])
let backup_dir = path(args[1])

source_dir
    |> files("**/*")
    |> where { file -> file.is_file and file.size > 100mib }
    |> for_each { file ->
    let target = path_join(backup_dir, file.name)
    print("copy", file.path, "->", target)
    copy(file.path, target, { overwrite: false })
}
    |> on_error { err ->
    print_error(err)
    throw(err)
}

hhy run --dry-run backup-large.hhy ./downloads ./backup
hhy run backup-large.hhy ./downloads ./backup

copy downloads/archive.tar -> backup/archive.tar
copy downloads/database.dump -> backup/database.dump
[dry-run] copy downloads/archive.tar → backup/archive.tar
[dry-run] copy downloads/database.dump → backup/database.dump

✓ exit 0 · plan generated without writing files

10.14Language basics in one task

A small aggregation task combining variables, Lists, Maps, functions, conditions, loops, scopes, and error handling. Corresponds to examples/07-language-basics.hhy.

fn summarize(items) {
    let mut total = 0

    for item in items {
        if item.enabled {
            total = total + item.score
        }
    }

    return total
}

let users = [
    { name: "Ada", enabled: true, score: 98 },
    { name: "Linus", enabled: false, score: 86 }
]

summarize(users) |> print

{
  "count": 2,
  "total": 40,
  "average": 20
}

✓ exit 0 · summary generated

11.1Start with one API

v1.4.3 contains the complete v1.4.0–v1.4.3 Web release train. Each worker loads the application once, handlers are reusable, and one failed request returns 500 without terminating later requests.

import web

fn hello(request) {
    web.json({ ok: true, name: request.query_params.name })
}

web.app()
    |> web.request_id
    |> web.health
    |> web.metrics
    |> web.gzip
    |> web.get("/hello", hello)
    |> web.listen({ host: "127.0.0.1", port: 8080, workers: 4 })

hhy serve app.hhy
hhy serve --dev app.hhy

11.2v1.4.3 capability boundary

11.3Use the HHY Web framework

HHY Web is a separate lightweight framework built on the v1.4.3 Web Runtime. It combines a Flask-inspired approachable API with Go-like explicit deployment, adding an application factory, five HTTP verbs, middleware, blueprints, stable Problem JSON, bearer authentication, uploads, Stream, and SSE helpers without duplicating the Router, worker model, or network stack.

View HHY Web on GitHub ↗
The public repository includes English and Chinese guides, Hello World, a complete JSON API, CLI, unit tests, and a real HTTP smoke test.
https://github.com/hh696-wq/hhy-web

git clone https://github.com/hh696-wq/hhy-web.git
cd hhy-web
./bin/hhy-web run examples/hello/app.hhy --port 8000 --dev
curl http://127.0.0.1:8000/

import "./lib/hhyweb.hhy" as hhyweb

fn hello(request) {
    return hhyweb.json({
        message: "Hello, HHY Web!",
        request_id: request.id
    })
}

hhyweb.minimal()
    |> hhyweb.get("/", hello)
    |> hhyweb.serve({ host: "127.0.0.1", port: 8000, workers: 1 })

12.1Scope and opt-in activation

Enabled by default: long-lived Context environments remain GC roots; Stream close releases payload references; supervised children have independent quota-failure recovery and teardown; portable no-replace uses exclusive publication. Language specification stays 1.0 and Database stays 1.0.0.

HHY_CONCURRENCY_EXPERIMENTS=1 hhy run --engine bytecode atomic-state.hhy
HHY_CONCURRENCY_EXPERIMENTS=1 hhy run --engine ast atomic-state.hhy
hhy contracts --format json

The shell variable above applies to one command. In PowerShell set $env:HHY_CONCURRENCY_EXPERIMENTS="1" and remove it afterward with Remove-Item Env:HHY_CONCURRENCY_EXPERIMENTS. Dry-run records contracts and returns Null; it neither executes callbacks nor validates their actual results.

12.2Atomicity and consistency guarantees

12.3Seven experimental APIs

atomic_state(data)

atomic_read(state)

atomic_update(state, callback)

atomic_close(state)

atomic_file_update(path, timeout, callback)

transaction_strict(config, options?, callback)

task_map(data, parallelism, result_limit, callback)

12.4State updates and handle ownership

let state = atomic_state({left: 0, right: 100})
fn transfer(old) { {left: old.left + 1, right: old.right - 1} }
atomic_update(state, transfer)
print(atomic_read(state))
atomic_close(state)

After this example, left is 1 and right is 99. atomic_update returns the new value and atomic_read reads an immutable snapshot. Data is limited to Null, Bool, Int, finite Float, String and recursive List/Map values with a depth limit of 128. Functions, Streams and handles cannot enter state.

12.5Effect contracts and commit state machine

strict_capability is pure, bound_transaction or external, with the Runtime contracts as the closed allowlist. Strict callbacks reject I/O, tasks, Streams, clocks, randomness, imports, assignments (including local mut) and nested strict scopes. Database callbacks additionally allow query/execute bound to the current tx. Third-party extensions cannot bypass restrictions by declaring themselves pure.

ACTIVE -> COMMITTING -> COMMITTED
   |           |----> ABORTED
   |           `----> UNKNOWN
   `----> ABORTED

12.6Cooperative single-file updates

fn increment(text) { encode_json(to_int(text) + 1) }
atomic_file_update(path(args[0]), 3s, increment) |> print

printf '0' > /tmp/hhy-counter.txt
HHY_CONCURRENCY_EXPERIMENTS=1 hhy run atomic-file.hhy /tmp/hhy-counter.txt

The file must already exist and the callback maps String to String. Lock-wait Duration must be positive and at most 300s; it is not a callback deadline. All writers must use the same path and <target>.hhy-lock protocol. Symlinks, multiple hard links and .hhy-lock target names are rejected. Keep the lock file while writers are active. Inode, ACL and extended-attribute preservation are not guaranteed.

12.7Restricted database transactions and durable idempotency

import database
let cfg = read_text(path(args[0])) |> parse_json
let n = cfg |> transaction_strict { tx ->
    database.execute(tx, "UPDATE counters SET n = n + 1 WHERE id = 1", [])
    return database.query(tx, "SELECT n FROM counters WHERE id = 1", []).rows[0].n
}
print(n)

Install Database 1.0.0 first, create a counters table with an existing id=1 row and integer n, then pass the database configuration JSON path as args[0]. Follow the database extension configuration format and keep credentials in local configuration. Options support the existing isolation/read_only settings.

Callbacks cannot use another tx, a pool, streaming handles, manual commit/savepoint, or return tx even nested in a result. MySQL implicit-commit statements are rejected. Effects inside stored procedures and triggers remain governed by the server; the Runtime cannot prove arbitrary SQL free of external effects.

Database installation and configuration
Database remains independently versioned at 1.0.0
/en/learn/database-extension

12.8Bounded tasks, cancellation and existing parallel

let results = [1, 2, 3] |> task_map(2, 1mib) { n -> n * 2 }
print(results)

The example returns [2, 4, 6] in input order. task_map eagerly maps a List to a List using isolated subprocesses; parallel keeps its existing Stream behavior. Parallelism is a positive integer bounded by Runtime limits. The 1b–256mib result budget limits cumulative accepted serialized results.

12.9Validation evidence and remaining limits

• 69 local engine/configuration cases; 10,000 commits per engine; GC, owner, quota and effect-denial tests.
• 80 competing file increments; native/portable no-replace races; MySQL/PostgreSQL tests with 32 requests, eight idempotency keys and dropped commit-acknowledgement reconciliation.
• A 120-second soak and 100,000-request Web acceptance passed; these are not a 24-hour soak, real power-loss test or general shared-memory linearizability proof.
• Four-platform CI and release validation passed; Windows artifacts use MSYS2 and exclude Database.
• HHY_BYTECODE_BINDING_CACHE=1 and HHY_STREAM_SOURCE_FUSION=1 remain separate, disabled-by-default experiments. Evidence does not justify default enablement or general speedup claims.

1.7.1 four-platform CI
f0fec9d · 2026-09-14
https://github.com/hh696-wq/hhy-vm/actions/runs/34805271378

Real-database acceptance
MySQL / PostgreSQL
https://github.com/hh696-wq/hhy-vm/actions/runs/34805271372

1.7.1 release notes and artifacts
Published; remaining 1.7.x candidates retain their individual acceptance gates
https://github.com/hh696-wq/hhy-vm/releases/tag/v1.7.1

12.10Offline Markdown guide

Download the English guide
Markdown version of this guide
/docs/CONCURRENCY_GUIDE.en.md

13.1Source files and lexical rules

13.2Literals and native units

let nothing = null
let flags = [true, false]
let numbers = [42, -10, 0xff, 0b1010, 1.5, 1e6]
let name = "HHY"
let strings = ["hello", "Hello, " + name]
let pattern = /ERROR|WARN/i
let list = [1, 2, 3]
let record = { name: "Tom", age: 20 }
let interval = 1..10
let units = [10mib, 5s, 80%]

Ranges include the start and exclude the end. Bytes support b/kb/mb/gb/kib/mib/gib; Duration supports ns/us/ms/s/min/h; % attached to a number creates Percent. In the current 1.7.1 runtime, {name} inside a string remains literal text. Use + to join strings, or pass multiple arguments to print for other value types. Strings support \, ", \n, \r, \t, \b, \f, and \0 escapes.

13.3Operator precedence (highest to lowest)

()  []  .
not  -  +
*  /  %
+  -
<  <=  >  >=
==  !=
and
or
??
|>
=

and, or, and ?? short-circuit; = may assign only to a let mut binding; |> is left-associative. Conditions require Bool—0, empty strings, and null are not implicitly false.

13.4Declarations, control flow, functions, and modules

let name = "HHY"
let mut count = 0
count = count + 1
let enabled = true
let items = ["Flow", "Pipe"]

if enabled { print("yes") } else { print("no") }
for item in items { print(item) }
while count < 3 { count = count + 1 }

fn add(a, b) { return a + b }
let doubled = [1, 2] |> stream |> map { number -> number * 2 } |> collect

try { read_text(path("config.json")) } catch err { print_error(err) }
let result = attempt { read_text(path("config.json")) }

import { add as sum_two } from "./math.hhy"
export fn public_api(value) { return value }

13.5Core value types

Null Bool Int Float String Regex BytesBuffer
List Map Range Function Error Result Stream
Bytes Duration Percent DateTime Path
File Directory FileEvent Process CommandResult
HttpRequest HttpResponse

14.1Reading the signatures

This page is sourced from the V1.7.1 Runtime Callable Contract Registry and contains all 128 core callables; dynamically registered callables are documented by their extensions. T/U are generic placeholders, ? marks an optional argument or nullable result, and Map? is an optional options Map. Every function supports ordinary calls; a pipe injects its left value as the first argument.

14.2Core values, collections, environment, and control (22)

print(Value...) -> Null

print_error(Value...) -> Null

exit(Int?) -> Never

length(String | List | Map) -> Int

byte_length(String | BytesBuffer) -> Int

type(Value) -> String

is_type(Value, String) -> Bool

to_int(Int | Float | String) -> Int

to_float(Int | Float | String) -> Float

get(List | Map | Record, Int | String) -> Value | Null

require(Map, String) -> Value

pick(Map, List<String>) -> Map

put(Map, String, Value) -> Map

remove_key(Map, String) -> Map

append(List<T>, T) -> List<T>

remove_at(List<T>, Int) -> List<T>

now() -> DateTime

datetime.parse(String, String, String) -> DateTime

require_env(String) -> String

sleep(Duration) -> Null

cancel() -> Never

throw(Error) -> Never

14.3Flow and Stream (25)

Transformations such as map, where, and take stay lazy; terminals such as collect, count, and reduce consume the Stream. sort_by and group_by materialize input within resource limits. parallel uses bounded isolated workers and preserves output order.

stream(List<T> | Map | Range) -> Stream<T>

range(Int, Int) -> Stream<Int>

map(Stream<T>, Function(T -> U)) -> Stream<U>

flat_map(Stream<T>, Function(T -> Stream<U>)) -> Stream<U>

where(Stream<T>, Function(T -> Bool)) -> Stream<T>

take(Stream<T>, Int) -> Stream<T>

skip(Stream<T>, Int) -> Stream<T>

inspect(Stream<T>, Function(T -> Value)) -> Stream<T>

distinct(Stream<Hashable>) -> Stream<Hashable>

sort_by(Stream<T>, Map, Function(T -> Comparable)) -> Stream<T>

group_by(Stream<T>, Function(T -> Hashable)) -> Stream<Group<T>>

debounce(Stream<T>, Duration) -> Stream<T>

on_error(Stream<T>, Function(Error -> Stream<T>)) -> Stream<T>

parallel(Stream<T>, Int, Function(T -> U)) -> Stream<U>

collect(Stream<T>) -> List<T>

count(Stream<T>) -> Int

first(Stream<T>) -> T | Null

last(Stream<T>) -> T | Null

min(Stream<Number>) -> Number | Null

max(Stream<Number>) -> Number | Null

sum(Stream<Number>) -> Number

reduce(Stream<T>, U, Function(State<T,U> -> U)) -> U

any(Stream<T>, Function(T -> Bool)) -> Bool

all(Stream<T>, Function(T -> Bool)) -> Bool

for_each(Stream<T>, Function(T -> Value)) -> Null

14.4Text, Regex, JSON, and CSV (18)

contains(String | List, Value) -> Bool

upper(String) -> String

lower(String) -> String

trim(String) -> String

trim_start(String) -> String

trim_end(String) -> String

starts_with(String, String) -> Bool

ends_with(String, String) -> Bool

replace(String, String, String) -> String

split(String, String) -> List<String>

join(List<String>, String) -> String

regex_match(String, Regex) -> Bool

regex_captures(String, Regex) -> Map | Null

url_resolve(String, String?) -> Map

parse_json(String) -> JsonValue

encode_json(JsonValue, Map?) -> String

parse_csv(String | Stream<String>, Map?) -> Stream<Map>

encode_csv(Stream<Map>, Map?) -> Stream<String>

14.5Paths, files, and watch (15)

read_* functions read data; write_text, write_bytes, save_text, and save_lines use a sibling temporary file plus atomic replacement. append_text appends to the target. Dry-run intercepts filesystem actions.

path(String) -> Path

path_join(Path, String | Path) -> Path

files(Path, String, Map?) -> Stream<File | Directory>

read_text(Path) -> String

read_lines(Path) -> Stream<String>

read_bytes(Path) -> BytesBuffer

write_text(Path, String, Map?) -> Path

append_text(Path, String) -> Path

write_bytes(Path, BytesBuffer, Map?) -> Path

save_text(String | Stream<String>, Path, Map?) -> Path

save_lines(Stream<String>, Path, Map?) -> Path

copy(Path, Path, Map?) -> Path

move(Path, Path, Map?) -> Path

remove(Path) -> Path

watch(Path, Map?) -> Stream<FileEvent>

14.6Processes, standard input, and timers (6)

run passes argv directly without a shell; only shell explicitly uses shell parsing. Process launches obey timeout, output, and process-count limits.

run(List<String>, Map?) -> CommandResult

shell(String, Map?) -> CommandResult

stdout_lines(CommandResult) -> Stream<String>

processes() -> Stream<Process>

stdin_lines() -> Stream<String>

every(Duration) -> Stream<Int>

14.7HTTP (10)

http.* only builds immutable request plans, timeout/retry transform a plan, and only send performs a network effect. response_body returns UTF-8 text; use response_bytes for binary data.

http.get(String, Map?) -> HttpRequest

http.post(String, Map?) -> HttpRequest

http.put(String, Map?) -> HttpRequest

http.delete(String, Map?) -> HttpRequest

timeout(HttpRequest, Duration) -> HttpRequest

retry(HttpRequest, Map) -> HttpRequest

send(HttpRequest) -> HttpResponse

send_to(HttpRequest, Path) -> HttpResponse

response_body(HttpResponse) -> String

response_bytes(HttpResponse) -> BytesBuffer

14.8Web Runtime (25)

web.* builds persistent applications, responses, middleware, and production endpoints; only web.listen binds a network port.

web.app() -> WebApp

web.get(WebApp, String, Function) -> WebApp

web.post(WebApp, String, Function) -> WebApp

web.put(WebApp, String, Function) -> WebApp

web.patch(WebApp, String, Function) -> WebApp

web.delete(WebApp, String, Function) -> WebApp

web.use(WebApp, Function) -> WebApp

web.static(WebApp, String, Path) -> WebApp

web.cors(WebApp, Map?) -> WebApp

web.request_id(WebApp) -> WebApp

web.health(WebApp, String?) -> WebApp

web.trust_proxy(WebApp) -> WebApp

web.text(String, Map?) -> WebResponse

web.html(String, Map?) -> WebResponse

web.json(JsonValue, Map?) -> WebResponse

web.redirect(String, Map?) -> WebResponse

web.response(Map) -> WebResponse

web.multipart(WebRequest, Path?) -> Map

web.stream(Stream, Map?) -> WebResponse

web.sse(Stream<String>) -> WebResponse

web.sign_cookie(String, String) -> String

web.verify_cookie(String, String) -> String | Null

web.metrics(WebApp, String?) -> WebApp

web.gzip(WebApp) -> WebApp

web.listen(WebApp, Map?) -> Null

14.9Controlled concurrency (7, experimental and disabled by default)

atomic_state(data)

atomic_read(state)

atomic_update(state, callback)

atomic_close(state)

atomic_file_update(path, timeout, callback)

transaction_strict(config, options?, callback)

task_map(data, parallelism, result_limit, callback)

Read the complete guide and examples
Includes the guarantee matrix, failure handling and actual validation evidence
/en/learn/concurrency-scopes

15.1HHY 1.7.1 implementation and compatibility

1.7.1 passes local tests, four-platform CI and release validation. Language specification 1.0 remains frozen. Official sample, HTML and macOS/Linux Database 1.0.0 extensions are verified compatible. VS Code 0.2.0 and Sublime 0.1.0 retain independent versions; syntax and editor contract checks pass.

HIR, six optimization passes, integer MIR, type-feedback guards/deopt and local List scalar replacement are implemented. Explicitly enable HHY_COMPILER=ir, HHY_FEEDBACK_SPECIALIZATION=1 and HHY_SCALAR_REPLACEMENT=1; direct Bytecode remains default. Real workloads have not met default-enablement benefit gates. Scalar replacement retains original GC/quota reservations.

Optimization switches, verification and supported scope
v1.7.1 implementation
/docs/COMPILER_IR.md

1.7.1 release notes
Released capabilities and limits
/docs/RELEASE_NOTES_1.7.1.md

15.2Version and release identity

Use --version to confirm the binary version, project author, open-source license, and official contact details. Source builds use ./build/hhy; release archives or PATH installations can invoke hhy directly.

hhy 1.7.1
© 2026 HHY Language contributors
Author: houhuiyang
License: Apache License 2.0
https://hhylang.dev/
huiyang.hou@qq.com

15.3Complete command set

hhy script.hhy [args...]
hhy run script.hhy [args...]
hhy run --engine ast|bytecode script.hhy [args...]
hhy repl
hhy check script.hhy...
hhy fmt script.hhy...
hhy fmt --check script.hhy...
hhy ast script.hhy
hhy bytecode script.hhy
hhy bytecode --metrics script.hhy
hhy tokens script.hhy
hhy run --dry-run script.hhy
hhy run --limit max_runtime=30s --limit max_memory=256mib script.hhy
hhy serve app.hhy [args...]
hhy serve --dev app.hhy [args...]
hhy serve --engine ast|bytecode --limit max_memory=256mib app.hhy -- [args...]
hhy profile script.hhy [args...]
hhy profile --engine ast|bytecode script.hhy [args...]
hhy profile --cpu script.hhy
hhy profile --heap --format json --output profile.json script.hhy
hhy check --format json script.hhy...
hhy contracts --format json
hhy install [--yes] [--dry-run] [--upgrade] [--locked] [--offline] [--lockfile FILE] [--cache DIR] [--registry DIR --trust-root FILE] <package-or-path>
hhy lock [--lockfile FILE] --registry DIR --trust-root FILE <package>
hhy fetch --locked [--lockfile FILE] [--cache DIR] --registry DIR --trust-root FILE
hhy rollback <package>
hhy doctor extensions [--lockfile FILE] [--cache DIR]
hhy list
hhy remove <package>
hhy --version
hhy -V
hhy --help
hhy -h

hhy script.hhy is shorthand for hhy run script.hhy. Use -- after Runtime options when script arguments may begin with a dash.

15.4serve · Persistent Web applications

serve loads and checks an HHY Web application, then keeps the process alive. --dev safely reloads after source changes; --engine selects AST or Bytecode; repeatable --limit options bound Runtime resources. HTTP settings such as host, port, max_body, and workers remain explicit in web.listen, while trailing positional values are exposed through read-only args.

hhy serve app.hhy
hhy serve --dev app.hhy -- 8080
hhy serve --engine bytecode \
  --limit max_memory=256mib \
  --limit max_runtime=30s \
  app.hhy -- 8080 production

15.5Bytecode cache admission evidence

v1.7.1 adds read-only --metrics output for measuring real compile+verify and execution-plan verification cost. Across five fixed workloads and 21 paired fresh-process samples, compile+verify medians were 0.004–0.012 ms, only 0.0078%–0.1341% of cold-run wall time, below the joint 1 ms and 20% thresholds.

{"bytecode_format_version":1,"compile_verify_ns":9000,"constants":21,"instructions":40,"schema_version":1,"source_bytes":167,"stream_kernel_version":1,"stream_kernels":1,"tool":"hhy bytecode --metrics","verify_prepare_ns":4000}

15.6CPU and Heap profiling

profile executes the script and collects CPU and managed-Heap data in the same run by default. Reports go to stderr, leaving script stdout unchanged, and the command preserves the script's exit code.

hhy profile examples/09-profile-algorithms.hhy -- fibonacci 20
hhy profile --cpu examples/09-profile-algorithms.hhy fibonacci 20
hhy profile --heap --format json --output profile.json examples/09-profile-algorithms.hhy fibonacci 20

HHY profile: examples/09-profile-algorithms.hhy

Summary
  Engine           bytecode
  Wall time        0.013 s
  CPU time         0.008 s
  CPU utilization  58.8%
  CPU samples      4
  Heap peak        1.8 MiB
  Heap after GC    92.0 KiB
  Allocated        1.7 MiB
  Allocations      33040

CPU hotspots
  CPU%    Samples      Calls  Function
   75.0%        3      21891  fibonacci  examples/09-profile-algorithms.hhy:5:1
   25.0%        1          1  print  examples/09-profile-algorithms.hhy:18:6
    0.0%        0          1  <bytecode-top-level>  examples/09-profile-algorithms.hhy:1:1
    0.0%        0          1  length  examples/09-profile-algorithms.hhy:12:10
    0.0%        0          1  to_int  examples/09-profile-algorithms.hhy:17:19
  Note: fewer than 10 CPU samples; use a larger workload for stable results.

Allocation hotspots
  Bytes          Objects  Function
  1.7 MiB            32856  fibonacci  examples/09-profile-algorithms.hhy:5:1
  11.6 KiB              184  <bytecode-top-level>  examples/09-profile-algorithms.hhy:1:1

fibonacci 6765

15.7Interpreter performance evolution

v1.7.1 defaults to the Compiler/Verifier-validated Bytecode VM. Native Opcode dispatch, static slots, reusable call frames, and low-allocation closure fast paths reduce CPU cost; the AST Interpreter remains the permanent semantic oracle and explicit fallback.

15.8Enable HIR / integer MIR

These are environment variables, not hhy subcommands. The commands below use macOS/Linux sh, bash or zsh; a prefix affects only that invocation. Use hhy after installation, or ./build/hhy in a source checkout. Save this file first.

fn calculate(x) { return x * 2 + 1 }
fn first(x) { return [x + 1, x * 2][0] }
for i in 0..32 {
    calculate(i)
    first(i)
}
print(calculate(20))
print(first(40))

# HIR only
HHY_COMPILER=ir hhy run --engine bytecode optimizer-demo.hhy

# Integer MIR only (direct compiler)
HHY_FEEDBACK_SPECIALIZATION=1 hhy run --engine bytecode optimizer-demo.hhy

# HIR + integer MIR + local List scalar replacement
HHY_COMPILER=ir HHY_FEEDBACK_SPECIALIZATION=1 HHY_SCALAR_REPLACEMENT=1 hhy run --engine bytecode optimizer-demo.hhy

# HIR report goes to stderr
HHY_COMPILER=ir HHY_COMPILER_REPORT=1 hhy bytecode --metrics optimizer-demo.hhy

# Runtime hits and deoptimizations go to profile.json
HHY_COMPILER=ir HHY_FEEDBACK_SPECIALIZATION=1 HHY_SCALAR_REPLACEMENT=1 hhy profile --engine bytecode --heap --format json --output profile.json optimizer-demo.hhy

For HIR, the stderr report has compiler=structured-ir; inspect passes and size_fallback. For MIR, typed_plans in Bytecode metrics counts compiled plans; typed_specialization.enabled and sites[].hits in profile.json show enablement and actual hits. scalar_reservations counts scalar reservations. On 2026-09-08, this example produced 26 hits per function and 26 scalar reservations for the List function; timings vary by host.

# Disable individual HIR passes; HIR remains enabled
HHY_COMPILER=ir HHY_COMPILER_DISABLE=fold,dce hhy run optimizer-demo.hhy

# Disable every HIR pass; HIR remains enabled
HHY_COMPILER=ir HHY_COMPILER_DISABLE=all hhy run optimizer-demo.hhy

# Restore the default compiler and disable MIR/scalar replacement (macOS/Linux)
unset HHY_COMPILER HHY_COMPILER_DISABLE HHY_COMPILER_REPORT HHY_FEEDBACK_SPECIALIZATION HHY_SCALAR_REPLACEMENT
hhy run --engine bytecode optimizer-demo.hhy

In Windows PowerShell, use this environment-variable syntax; remove the variables afterward to restore defaults.

$env:HHY_COMPILER="ir"
$env:HHY_FEEDBACK_SPECIALIZATION="1"
$env:HHY_SCALAR_REPLACEMENT="1"
hhy run --engine bytecode optimizer-demo.hhy
Remove-Item Env:HHY_COMPILER, Env:HHY_FEEDBACK_SPECIALIZATION, Env:HHY_SCALAR_REPLACEMENT

15.9Runtime resource limits

The run command accepts repeatable --limit NAME=VALUE options. Sizes require b/kb/mb/gb/kib/mib/gib, durations require ns/us/ms/s/min/h, and counts have no unit.

hhy run --limit max_runtime=30s --limit max_memory=256mib script.hhy

15.10Stable exit codes

0  success
1  unhandled runtime error
2  syntax or static-check error
3  invalid CLI usage
4  file I/O, process, or network error
5  timeout or cancellation

Automation should branch on stable exit codes rather than error text.

16.1HHY 1.7.1 implementation and compatibility

1.7.1 passes local tests, four-platform CI and release validation. Language specification 1.0 remains frozen. Official sample, HTML and macOS/Linux Database 1.0.0 extensions are verified compatible. VS Code 0.2.0 and Sublime 0.1.0 retain independent versions; syntax and editor contract checks pass.

HIR, six optimization passes, integer MIR, type-feedback guards/deopt and local List scalar replacement are implemented. Explicitly enable HHY_COMPILER=ir, HHY_FEEDBACK_SPECIALIZATION=1 and HHY_SCALAR_REPLACEMENT=1; direct Bytecode remains default. Real workloads have not met default-enablement benefit gates. Scalar replacement retains original GC/quota reservations.

Optimization switches, verification and supported scope
v1.7.1 implementation
/docs/COMPILER_IR.md

1.7.1 release notes
Released capabilities and limits
/docs/RELEASE_NOTES_1.7.1.md

16.2The current extension boundary

A package name is its top-level namespace: package_name may register only package_name.* and cannot replace hhy.*, std.*, core callables, or another package. Importing an uninstalled package raises ModuleNotFoundError.

16.3Available official extensions

Database Extension Guide
Install database 1.0.0 for pools, remote TLS, transactions and streaming queries.
/en/learn/database-extension

HTML Extension and Crawler Framework
Use html 0.2.0 with observable batch extraction, URL normalization, a safe frontier, deduplication, and SSRF protection.
/en/learn/html-crawler-framework

16.4Where to get extensions

# Build and install from source (html example)
git clone https://github.com/hh696-wq/hhy-vm.git
cd hhy-vm
make
make -C extensions/html
./build/hhy install ./extensions/html

# Inspect installed extensions
./build/hhy list

Open the official extension index ↗
One extension version may contain darwin-arm64, linux-x86_64, linux-arm64, and windows-x86_64 targets; the installer selects only its native target.
https://registry.hhylang.dev/index.json

Browse extension source on GitHub ↗
Source, hhy.toml manifests, tests, and build scripts for sample, html, and database.
https://github.com/hh696-wq/hhy-vm/tree/main/extensions

16.5Install, list, and remove

./build/hhy install ./path/to/extension
./build/hhy list
./build/hhy remove package-name

16.6Generic hhy.toml manifest

[package]
name = "package-name"
version = "0.1.0"
author = "Your Organization"
requires_hhy = ">=1.1,<2.0"

[extension]
kind = "process"
command = "bin/hhy-package"
protocol = "1"

[capabilities]
read = []
write = []
network = []
process = false

16.7How an extension loads

16.8What an extension author must implement

The extension process does not receive the complete host environment; Runtime passes only arguments explicitly supplied by the script. Errors should remain actionable without including passwords, tokens, complete connection addresses, or other sensitive information.

17.11.7.1 controlled concurrency and atomicity

This release fixes resource lifetimes and delivers seven experimental APIs, disabled by default. Review state ownership, cooperative file locks, strict transactions and bounded-task guarantees before enabling them.

Read the complete guide and examples
Includes the guarantee matrix, failure handling and actual validation evidence
/en/learn/concurrency-scopes

17.2Version and installation

Download Database 1.0.0
HHY 1.5.0 · Database 1.0.0
https://github.com/hh696-wq/hhy-vm/releases/tag/database-v1.0.0

hhy --version
# Extract the matching release archive and preserve bin/ and lib/
hhy install ./hhy-database-1.0.0-darwin-arm64
hhy list

# Or build from the repository root
make -C extensions/database
./build/hhy install ./extensions/database

17.3Data sources and remote TLS

{
  "driver": "mysql",
  "host": "127.0.0.1",
  "port": 3306,
  "user": "cms_test",
  "password": "CHANGE_ME",
  "database": "hhy_test",
  "allow": [
    "127.0.0.1:3306"
  ],
  "tls": "disabled",
  "max_open": 4,
  "max_idle": 2,
  "connect_ms": 5000,
  "acquire_ms": 1000,
  "timeout_ms": 30000
}

Legacy URLs remain supported for loopback. Use maps for remote endpoints and pool options. MySQL uses ? and PostgreSQL uses $1, $2; identifiers cannot be value parameters. The allow list is trusted-script policy, not an OS sandbox.

17.4Pools and queries

import database
let cfg = read_text(path(args[0])) |> parse_json
database.query(cfg, "SELECT ? AS value", [42], { typed: true }) |> print
database.stats() |> print

hhy run query.hhy ./config.local.json

Pools are isolated by data source and extension process. Defaults are max_open=4 and max_idle=2; add worker budgets together. Idle/lifetime retirement, resets, acquire timeouts and metrics are supported. Duration options such as timeout_ms: 5s work directly. Results default to String/null; typed mode preserves numeric types, exact envelopes preserve decimals/large integers and binary maps to BytesBuffer.

17.5Transactions and streaming

import database
let cfg = read_text(path(args[0])) |> parse_json
cfg |> database.with_transaction { tx ->
    database.execute(tx, "UPDATE pages SET title = ? WHERE id = ?", ["Hello HHY", 1])
    database.query(tx, "SELECT id, title FROM pages WHERE id = ?", [1])
} |> print

import database
let cfg = read_text(path(args[0])) |> parse_json
database.stream(cfg, "SELECT id, title FROM pages ORDER BY id", [])
    |> take(100)
    |> collect
    |> print

Streams pull batches; take closes results early. Handles cannot cross requests/workers or survive close; request completion cleans abandoned resources. Unread results can discard a physical connection, so early stream closure inside a transaction may invalidate that transaction.

17.6API and limits

17.7Acceptance and installation scenarios

MySQL 8.4/PostgreSQL 17 pass local/CI, AST/Bytecode, two-worker, TLS positive/negative, cancellation and sanitizer acceptance, plus local million-row streaming. An install.hhy database fixture covers failure recovery, repeat installation, failed upgrade rollback and backup restoration; it is not a full CMS. Local sustained tests ran five minutes per backend, not a 24-hour soak or RDS failover certification.

Full API and migration guide
HHY 1.5.0 · Database 1.0.0
/docs/DATABASE_1.0.0_README.md

Measurements and reproduction
HHY 1.5.0 · Database 1.0.0
/docs/DATABASE_1.0.0_ACCEPTANCE.md

View passing release Actions
HHY 1.5.0 · Database 1.0.0
https://github.com/hh696-wq/hhy-vm/actions/runs/34079510695

18.1What the HTML extension is

The official html 0.2.0 package is a process extension with no network or filesystem effects. Lexbor parses untrusted HTML, evaluates CSS selectors, and extract_report returns batch rows with explicit truncation metadata.

18.2Build and install the HTML extension

brew install jansson lexbor
make -C extensions/html
./build/hhy install ./extensions/html
./build/hhy list

The extension limits input to 768 KiB, keeping protocol messages bounded. extract schema fields use { selector, value: "text" } or { selector, value: "attr", name }; an empty selector reads the current root. It does not return DOM handles: Protocol 1 transports only JSON-shaped values, so html.extract performs parsing and projection inside one extension call.

18.3From HTML extraction to a safe crawler

The static spider composes separate responsibilities: Runtime url_resolve normalizes relative references; the HTML extension discovers links; a depth frontier checks domains, paths, page and queue budgets, and fingerprints before admission; the HTTP layer blocks SSRF at the resolved connection address.

18.4Scope and explicit boundaries

The crawler supports an in-memory or atomically checkpointed frontier, strict configuration-matched resume, and send_to response files. An optional Playwright renderer executes JavaScript separately from the side-effect-free Lexbor extension and applies domain plus DNS private-network checks to documents, redirects, and subresources.

19.11.7.1 controlled concurrency and atomicity

This release fixes resource lifetimes and delivers seven experimental APIs, disabled by default. Review state ownership, cooperative file locks, strict transactions and bounded-task guarantees before enabling them.

Read the complete guide and examples
Includes the guarantee matrix, failure handling and actual validation evidence
/en/learn/concurrency-scopes

19.2HHY 1.7.1 implementation and compatibility

1.7.1 passes local tests, four-platform CI and release validation. Language specification 1.0 remains frozen. Official sample, HTML and macOS/Linux Database 1.0.0 extensions are verified compatible. VS Code 0.2.0 and Sublime 0.1.0 retain independent versions; syntax and editor contract checks pass.

HIR, six optimization passes, integer MIR, type-feedback guards/deopt and local List scalar replacement are implemented. Explicitly enable HHY_COMPILER=ir, HHY_FEEDBACK_SPECIALIZATION=1 and HHY_SCALAR_REPLACEMENT=1; direct Bytecode remains default. Real workloads have not met default-enablement benefit gates. Scalar replacement retains original GC/quota reservations.

Optimization switches, verification and supported scope
v1.7.1 implementation
/docs/COMPILER_IR.md

1.7.1 release notes
Released capabilities and limits
/docs/RELEASE_NOTES_1.7.1.md

19.3Language / VM Evolution Roadmap

Current v1.7.1 · Database 1.0.0 released alongside the complete Web Runtime

19.4Future plans

The roadmap prioritizes atomicity, shared state, coroutines and distributed transactions, grouped by major release series. These are planned goals; unfinished capabilities are not guarantees of 1.7.1.

Release directions are not calendar commitments. In 1.7.1, HHY_CONCURRENCY_EXPERIMENTS=1 already enables the seven experimental APIs. Stable API availability and default optimization are separate decisions; missed gates delay admission without lowering thresholds.

Read current atomicity and concurrency guarantees
Separate supported behavior, experiments and future plans
/en/learn/concurrency-scopes

19.5Evolution principles

Review the roadmap once per quarter. Only unfrozen releases may move; scheduling changes must not weaken published semantics, compatibility commitments, or migration paths.

19.6Explicit non-commitments

• No second Pipe, Stream, or Error model merely to justify a release number.
• No public exposure of internal Runtime C structures without a compatibility strategy.
• No use of recommended windows as a reason to skip testing, security, or cross-platform validation.
• No simultaneous rush into a remote registry, Native ABI, and multiple official extensions before stage gates pass.

20.1HHY 1.7.1 implementation and compatibility

1.7.1 passes local tests, four-platform CI and release validation. Language specification 1.0 remains frozen. Official sample, HTML and macOS/Linux Database 1.0.0 extensions are verified compatible. VS Code 0.2.0 and Sublime 0.1.0 retain independent versions; syntax and editor contract checks pass.

HIR, six optimization passes, integer MIR, type-feedback guards/deopt and local List scalar replacement are implemented. Explicitly enable HHY_COMPILER=ir, HHY_FEEDBACK_SPECIALIZATION=1 and HHY_SCALAR_REPLACEMENT=1; direct Bytecode remains default. Real workloads have not met default-enablement benefit gates. Scalar replacement retains original GC/quota reservations.

Optimization switches, verification and supported scope
v1.7.1 implementation
/docs/COMPILER_IR.md

1.7.1 release notes
Released capabilities and limits
/docs/RELEASE_NOTES_1.7.1.md

20.2Download language packages

Packages provide .hhy highlighting, brackets, indentation and snippets. VS Code also uses the hhy CLI for diagnostics, formatting, definitions, hover and completion; install HHY Runtime first. Plugin versions are independent of the Runtime.

Download editor packages locally
Installable VSIX and sublime-package files with SHA-256 checksums.
/en/downloads#editors

20.3Install in VS Code

code --install-extension ./hhy-language-support-0.2.0.vsix

Run from your download directory, or choose Install from VSIX in the VS Code Extensions menu. Then open a .hhy file.

20.4Install in Sublime Text

Copy the downloaded HHY-0.1.0.sublime-package into Sublime Text's Installed Packages directory, then open a .hhy file.

21.11.7.1 controlled concurrency and atomicity

This release fixes resource lifetimes and delivers seven experimental APIs, disabled by default. Review state ownership, cooperative file locks, strict transactions and bounded-task guarantees before enabling them.

Read the complete guide and examples
Includes the guarantee matrix, failure handling and actual validation evidence
/en/learn/concurrency-scopes

21.2HHY 1.7.1 implementation and compatibility

1.7.1 passes local tests, four-platform CI and release validation. Language specification 1.0 remains frozen. Official sample, HTML and macOS/Linux Database 1.0.0 extensions are verified compatible. VS Code 0.2.0 and Sublime 0.1.0 retain independent versions; syntax and editor contract checks pass.

HIR, six optimization passes, integer MIR, type-feedback guards/deopt and local List scalar replacement are implemented. Explicitly enable HHY_COMPILER=ir, HHY_FEEDBACK_SPECIALIZATION=1 and HHY_SCALAR_REPLACEMENT=1; direct Bytecode remains default. Real workloads have not met default-enablement benefit gates. Scalar replacement retains original GC/quota reservations.

Optimization switches, verification and supported scope
v1.7.1 implementation
/docs/COMPILER_IR.md

1.7.1 release notes
Released capabilities and limits
/docs/RELEASE_NOTES_1.7.1.md

21.31.7.0 measured results and release evidence

One local macOS arm64 run on 2026-09-08 with HHY 1.7.0 and default compiler settings. The raw profiler output follows. Only four CPU samples were collected; short-run timings and hotspot percentages vary and do not establish a speedup.

HHY profile: examples/09-profile-algorithms.hhy

Summary
  Engine           bytecode
  Wall time        0.013 s
  CPU time         0.008 s
  CPU utilization  58.8%
  CPU samples      4
  Heap peak        1.8 MiB
  Heap after GC    92.0 KiB
  Allocated        1.7 MiB
  Allocations      33040

CPU hotspots
  CPU%    Samples      Calls  Function
   75.0%        3      21891  fibonacci  examples/09-profile-algorithms.hhy:5:1
   25.0%        1          1  print  examples/09-profile-algorithms.hhy:18:6
    0.0%        0          1  <bytecode-top-level>  examples/09-profile-algorithms.hhy:1:1
    0.0%        0          1  length  examples/09-profile-algorithms.hhy:12:10
    0.0%        0          1  to_int  examples/09-profile-algorithms.hhy:17:19
  Note: fewer than 10 CPU samples; use a larger workload for stable results.

Allocation hotspots
  Bytes          Objects  Function
  1.7 MiB            32856  fibonacci  examples/09-profile-algorithms.hhy:5:1
  11.6 KiB              184  <bytecode-top-level>  examples/09-profile-algorithms.hhy:1:1

fibonacci 6765

View 1.7.0 CI and raw performance artifacts
8fb0b8f · 2026-09-08
https://github.com/hh696-wq/hhy-vm/actions/runs/34197497786

21.4Release summary

21.5Data at a glance

21.6v1.5.0 / Database 1.0.0 release acceptance

Released 2026-09-07. Dual-database/engine, TLS, scope cleanup, cancellation, CMS database lifecycle and cross-platform release gates pass. Local million-row streaming and five-minute-per-backend sustained reports are available. RDS and 24-hour soak validation remain pending.

Read DB 1.0.0 acceptance
HHY 1.5.0 · Database 1.0.0
/docs/DATABASE_1.0.0_ACCEPTANCE.md

Read HHY 1.5.0 release notes
HHY 1.5.0 · Database 1.0.0
/docs/RELEASE_NOTES_1.5.0.md

21.7v1.4.3 Web Runtime and release verification

Read the v1.4.3 release-validation record
Site-hosted release notes with test scale, results, and capability boundaries.
/docs/RELEASE_NOTES_1.4.3.md

21.8Current capability boundaries

21.9Overall baseline and compatibility

The current formal baseline is v1.7.1. Bytecode is default; the AST evaluator remains the semantic oracle and is selectable through --engine ast or HHY_ENGINE=ast. Compiler-produced Stream Kernels must pass their independent Verifier; dynamic and unknown shapes fall back losslessly to general Bytecode.

21.10v1.2.2 release and extension status

Open the HHY Language v1.2.2 release
Download all four platform archives and checksums and read the release notes.
https://github.com/hh696-wq/hhy-vm/releases/tag/v1.2.2

21.11v1.3.7–v1.3.10 Bytecode hardening

Open the HHY Language v1.7.1 release
Four platform archives, per-asset SHA-256, SHA256SUMS, and Web Runtime release notes.
https://github.com/hh696-wq/hhy-vm/releases/tag/v1.7.1

21.12Historical performance baseline · v1.3.10

Final v1.3.10 CI evidence comes from commit 4ddc8c3 on GitHub Actions Ubuntu 24.04: schema-2 paired/interleaved engine benchmarks plus independent Profiler and cache-decision artifacts. Ratios are Bytecode/AST wall time; lower than one means Bytecode is faster.

21.13v1.3.10 six-runtime same-machine rerun

Rerun on 2026-09-01 on macOS 26.6.2 arm64 with HHY 1.3.10, PHP 8.5.10, Go 1.27.0, Python 3.14.7, Lua 5.5.1, and OpenJDK 26.0.2.1. The fixed task maps, filters, stable-distincts, materializes, and counts one million integers; all six implementations validate output 333334. After two warmups, two independent rounds use seven deterministically shuffled and interleaved fresh processes per runtime. Wall time includes process startup; Go and Java are precompiled and compile time is excluded.

21.14Governance conclusion and watch list

• Overall status: v1.7.0 / DB 1.0.0 passed local, CI and cross-platform release gates; real RDS and 24-hour soak validation remain pending.
• Web conclusion: embedding, HTTP, Router, middleware, uploads, Stream/SSE, multi-worker serving, and observability ship together.
• Engine policy: Bytecode is default; AST remains permanently available as the semantic oracle, differential-test engine, and --engine ast emergency fallback.
• Performance conclusion: one million Web short requests completed with zero failures; existing CPU, short-task, sustained-JSON, and Profiler gates continue to pass.
• Cache conclusion: compile+verify is not a major cold-run cost; no cache is introduced until new data triggers review.
• Update rule: synchronize this report whenever the release baseline, measurement method, engine/cache decision, or overall risk conclusion changes.

Open v1.3.11 continuous-verification evidence
Four-platform builds, sanitizers, fuzzing, performance gates, and practical-project acceptance.
https://github.com/hh696-wq/hhy-vm/actions/runs/33581452558