Roadmap · Not implemented

Extension System Roadmap

Preview the planned extension installation, loading, process protocol, and a Redis extension example; none of these capabilities is implemented in v1.0.

Status first: v1.0 has no extension support

Capability	v1.0 status	Target
Extension module names and core contracts	Internal boundaries reserved	v1.0
Local extension installation and loading	Not implemented	v1.1
Official office extension	Not implemented	v1.2
Public Native ABI	Not committed	Evaluate after Runtime stabilization

v1.0 accepts qualified module names such as import office.excel; an absent module produces ModuleNotFoundError. This only reserves syntax for future extensions and does not mean that the module exists.

Release path

v1.0   Core contracts and namespace reservation
v1.1   Process Extension Protocol + local package installation
v1.2   Official office extension validates the protocol
later  Evaluate a public Native ABI after Runtime stabilization

Core remains responsible for Pipe, Value, Stream, Error, cancellation, effects, and resource lifecycles. Extensions only register new callables, types, or data streams; they cannot change HHY syntax or create a separate Stream model.

Planned install, list, and remove commands

# Planned commands; not executable in v1.0
hhy install ./hhy-redis
hhy list
hhy remove redis

Step	Planned behavior
install	Read local hhy.toml, verify versions, executable and integrity hash, then display capabilities before installation
load	On import, start an isolated extension process, handshake, and register callables
list	Show locally installed packages, versions, protocols, and capabilities
remove	Remove the package record and clean up extension resources no longer in use

Planned hhy.toml manifest

[package]
name = "redis"
version = "0.1.0"
requires_hhy = ">=1.1,<2.0"

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

[capabilities]
read = []
write = []
network = ["redis.example.com:6379"]
process = false

The package name supplies a unique top-level namespace; hhy.* and std.* are reserved. The installer grants only declared, user-approved minimum capabilities, and an upgrade that adds capabilities requires confirmation again.

How an extension will load

v1.1 plans a process-first model: Runtime starts a separate executable, completes a protocol handshake, receives function, type, operator, and action registrations, then connects them to the same Callable Contract Registry. A process crash becomes an HHY Error instead of taking down the interpreter.

Protocol stage	Responsibility
handshake	Negotiate extension_id, protocol_version, and compatibility
register	Declare names, inputs, outputs, effect, lazy, cancel, and threading metadata
call / call_result	Invoke by request_id and return a value or structured error
stream_*	Provide chunked Streams with items, credit/window backpressure, and close
cancel / shutdown	Propagate cancellation and idempotently release processes, Streams, and handles

Redis extension design example

# Possible future layout; v1.0 will not load it
hhy-redis/
├── hhy.toml
└── bin/hhy-redis

# Possible future HHY calls; not executable today
import redis

let client = redis.connect({ url: require_env("REDIS_URL") })
client |> redis.set("health", "ok")
let value = client |> redis.get("health")
client |> redis.scan("session:*") |> take(100) |> collect()

Illustrative callable	Possible contract
redis.connect	Has a network effect; returns a non-serializable RedisClient handle
redis.get	Accepts client and key; returns String, Bytes, or Null
redis.set	Has a network effect and must participate in dry-run and capability auditing
redis.scan	Returns a lazy Stream and must support backpressure, cancellation, and early close

What an extension author must implement

Part	Requirement
Executable process	Handshake, register, and serve calls over the standard protocol channel
Contracts	Declare input, output, effect, laziness, cancellation, and threading for every callable
Value conversion	Use protocol-serializable values and controlled Opaque handles for external connections
Streams	Honor pull behavior, credit backpressure, cancellation, errors, and close lifecycle
Security	Use a minimal environment, explicit secret providers, and never bypass capabilities
Tests	Cover handshake failure, timeout, cancellation, crashes, cleanup, and incompatible versions

A public Native ABI is not a prerequisite for v1.1. It will only be considered, using opaque handles and function tables, if the process protocol is insufficient and performance measurements demonstrate a need.