HHY Extension · Current version v1.7.1

Extension System

The v1.7.1 process-extension model: the signed official Registry, source builds, manifests, capabilities, Protocol 1, and callable registration.

HHY 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 scopev1.7.1 implementation 1.7.1 release notesReleased capabilities and limits

The current extension boundary

Capability	Current status	Boundary
Extension distribution	Implemented	Signed official Registry or local source builds; identity, target, signatures, and file hashes are verified before installation
Process protocol	Implemented	handshake, register, call, call_result, error, shutdown
Value transport	Implemented	JSON protocol mapping for Null, Bool, numbers, String, List, and Map
DB Stream / handle / cancel	Implemented for DB 1.0	Negotiated scoped_resources, scoped handles and cancellation; DB Streams pull cursors rather than providing generic Stream transport
Public Native ABI	Not committed	Evaluate only if measurements show the process model is insufficient

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.

Available official extensions

Extension	Version	Published	Status	Capability
database	1.0.0	2026-09-07	Released	MySQL/PostgreSQL pools, remote TLS, transactions, prepared statements, cursors and exact types
html	0.2.0	2026-09-01	Released	Lexbor CSS selectors, text/attribute reads, and structured extraction

Database Extension GuideInstall database 1.0.0 for pools, remote TLS, transactions and streaming queries.HTML Extension and Crawler FrameworkUse html 0.2.0 with observable batch extraction, URL normalization, a safe frontier, deduplication, and SSRF protection.

Where to get extensions

Source	Best for	Address or action
Official HHY Registry	Downloading signed official extensions for a specific platform	https://registry.hhylang.dev (index: /index.json; trust root: /root.json)
GitHub source	Reviewing code, auditing changes, or building from source	https://github.com/hh696-wq/hhy-vm/tree/main/extensions
Local source build	Extension development or a custom local dependency combination	make -C extensions/<name>, then install the local directory

# 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.Browse extension source on GitHub ↗Source, hhy.toml manifests, tests, and build scripts for sample, html, and database.

Install, list, and remove

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

Step	Actual behavior
install	Read hhy.toml; validate package name, author, requires_hhy, protocol, command, and integrity; display capabilities and ask the user to confirm
import / load	Recheck installed SHA-256 data, start the extension process, handshake, and register callables
list	Display each installed package's name, version, author, protocol, and declared capabilities
remove	Delete the local package record and installation directory; subsequent imports fail

Generic 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

Field	Developer constraint
package.name	Unique top-level namespace using lowercase letters, digits, and hyphens
package.author	Shown during install and list to identify official or third-party provenance
requires_hhy	Runtime version range checked by the installer
extension.command	Must be an executable under the package bin/ directory and cannot escape its root
extension.protocol	Currently accepts Protocol 1
capabilities	Declares file, network, and subprocess access for review

How an extension loads

How an extension loadsHHY extension loading architecture

1HHY scriptImport a packageimport package_name

2RuntimeValidate and initializeVerify manifest and SHA-256

3Extension processStart isolated process

bin/hhy-package
--protocol 1

4Protocol registrationRegister callable capability

handshake
register callables

5ImplementationHandle protocol values

Null / Bool / Number
String / List / Map

6Call executionReturn result or error

call_result
or structured Error

Structured error returnProtocol or call failure → Runtime Error → HHY script

IntegrityVerify SHA-256 on install and load

Standard protocolProtocol 1 interoperability

Capability registryDynamic registration inside the package namespace

Unified responseStructured results and errors

1.7.1 extension load path · isolated process · Runtime owns validation, protocol dispatch, and HHY value conversion

Stage	Runtime and extension responsibility
resolve	Runtime resolves import package_name to an installed package, parses its manifest, and validates command integrity
spawn	Runtime starts a separate process with --protocol 1 and opens stdin/stdout protocol pipes
handshake	Both sides confirm extension_id and protocol_version=1.0
register	The extension sends one registration message; Runtime validates its package namespace and contracts
call	Runtime sends serializable arguments; request_id correlates each call and call_result
shutdown	Runtime sends shutdown and reaps protocol streams and the child process

What an extension author must implement

Part	Requirement
Package	Provide hhy.toml, an in-package executable command, and SHA-256 integrity data verifiable by the installer
Startup	Accept only --protocol 1; write protocol messages only to stdout and logs to stderr
Handshake	Validate extension_id and protocol_version and return matching identity
Register	Send exactly one initial registration; every name must stay in the package namespace and provide a valid contract
Call	Return call_result or structured error for each request_id without exposing credentials or sensitive diagnostics
Shutdown	Idempotently release connections, memory, and other extension resources
Tests	Cover identity mismatch, invalid arguments, extension exit, protocol errors, and resource cleanup

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.