Files
skills/public/hip-0138.md

48 KiB
Raw Permalink Blame History

hip, title, author, type, category, status, created, updated, requires
hip title author type category status created updated requires
0138 Cloud — Unified Hanzo Binary Hanzo AI Team Standards Track Infrastructure Final 2026-05-19 2026-07-08 HIP-0014, HIP-0026, HIP-0027, HIP-0029, HIP-0105, HIP-0302

HIP-0138: Cloud — Unified Hanzo Binary

This document was numbered HIP-0106. That number is the plugin contract's — HIP-0116 and the code both cite it that way — so this one took the next free number in its block.

Abstract

This proposal defines cloud — a single Go binary that imports every Hanzo-native subsystem as a package and dispatches requests to them by HTTP path, subsystem flag, or per-deployment configuration. The same binary powers api.hanzo.ai, api.osage.cloud, api.lux.cloud, api.zoo.cloud, and every other white-label resold cloud surface. Brand, enabled subsystems, and tenant scope are deployment configuration; the binary is the same artifact across all.

Naming note (2026-05-19 rename): the unified binary lives at hanzoai/cloud (this repo); the former LLM-control-plane content that used to live at hanzoai/cloud was renamed to hanzoai/ai and is now mounted as the ai subsystem inside this binary. White-label fork target is hanzoai/cloud — customers fork this one repo to launch their own ecosystem.

Inter-subsystem contract: ZAP (the Hanzo native binary protocol). Every subsystem ships its public interface as a .zap schema; zapc generates Go/TS/Python/Rust bindings; cloud wires the in-process ZAP-typed Go interfaces when subsystems are co-resident, falls back to ZAP RPC over the wire when split. No .capnp files anywhere in Hanzo-authored code.

Transport boundary — ZAP only, day one. Every Hanzo-authored transport AND data type is ZAP. There is no gRPC and no protobuf anywhere in Hanzo-authored code — zero google.golang.org/grpc, zero google.golang.org/protobuf, zero .proto, zero .pb.go. The only historical gRPC was dead Temporal-porting codegen, removed in hanzoai/tasks#12. Where an external standard must be spoken at the interop edge (OpenTelemetry OTLP for trace/log ingest, OpAMP for agent management), the protobuf wire is produced by the zap tooling — pb2zap converts the external .proto to a .zap schema (compiled by zapc to ZAP-native Go types), and zap2pb marshals those ZAP structs back to protobuf wire bytes at the boundary. Hanzo code holds only ZAP types and calls the generated converter; protobuf lives exclusively inside the ~/work/zap converter tool, never in a Hanzo service. Transitive protobuf pulled by foundational dependencies (beego/authz/coraza/lego/otel, and even luxfi/metric/client) is a dependency-side follow-up, not Hanzo-authored code.

Motivation

Today Hanzo ships ~11+ Go-native services as independent binaries: IAM, Base, KMS, Gateway, Ingress, Commerce, AI (LLM control plane subsystem), o11y, AMQP, MCP (Go path), DNS, VFS, MQ, Authz, Agents. Each gets its own Dockerfile, Helm chart, deploy lane, CI workflow, release cadence, and observability spine. For Hanzo this is acceptable — we operate the cluster. For white-label resell (lux.cloud, zoo.cloud, osage.cloud, and others) it's not: every customer needs the same constellation of services, isolated per-tenant, billed per-tenant, auth'd against unified IAM. Shipping 11+ binaries × N customers × 3 environments multiplies operational surface beyond what a small team should run.

The audit at ~/work/hanzo/AUDIT_2026_05_19.md confirms ~35 Go-native services structurally ready for inclusion, of which 3 already export func Mount(r, deps) — commerce, gateway, and vfs. These are the reference implementations.

The unified binary collapses this:

  1. One artifact, ghcr.io/hanzoai/cloud:vX.Y.Z, that contains every Hanzo Go subsystem as compiled code.
  2. Deployment configuration at startup enables a subset of subsystems (cloud --enable=iam,base,kms,commerce,gateway,ai).
  3. Per-tenant routing at request time: X-Org-Id from JWT picks the tenant's Base instance, KMS namespace, IAM application, and brand.
  4. Multi-tenant Base at the storage layer per HIP-0302: each tenant org gets its own per-tenant data file (data/{orgSlug}.db for the SQLite backend, equivalent path for the ZapDB backend) with a per-org HKDF-derived DEK from a master key in KMS. Replicate works for both backends — SQLite WAL streaming and ZapDB-native log shipping use the same age-encrypted GCS bucket sink. Already the pattern in ~/work/hanzo/iam and ~/work/hanzo/base; this HIP makes it the universal contract.
  5. Unified IAM auth at the boundary per HIP-0026: every subsystem trusts JWTs from one shared iam.hanzo.id JWKS endpoint. Gateway strips client-supplied identity headers, mints validated ones from the JWT, forwards in-process.
  6. ZAP-typed interfaces between subsystems. Same generated Go code serves both in-process direct calls and over-wire RPC. Bootnode and other subsystems already use this pattern via zapc (the Hanzo ZAP compiler, Rust impl at ~/work/hanzo/zap/zapc-rs/) today.

Specification

Wire protocol stack

JSON crosses the system boundary exactly once per request. Inside, every inter-subsystem call is ZAP-typed Go values — direct method calls when co-resident, ZAP RPC when split. JSON re-marshalling between Hanzo subsystems is a defect.

External clients
  └── HTTP + JSON (stdlib encoding/json/v2 via hanzoai/zip jsonenc)
        ↓
ingress (TLS termination, log, rate limit)
  └── ingress hands the request to gateway with the JSON body intact
        ↓
gateway (JWT validation, identity-header mint, route)
  └── gateway hands the request to the subsystem with X-Org-Id +
      the validated JWT; the body is still JSON until the subsystem
      handler parses it
        ↓
subsystem handler (e.g. commerce, ai, mcp)
  └── parses JSON body via zip.Ctx.Bind() — encoding/json/v2 when
      GOEXPERIMENT=jsonv2, encoding/json v1 otherwise
  └── inter-subsystem calls via cloud.Deps clients — ZAP-typed Go
      values, no JSON re-marshal (in-process: direct method calls;
      split: ZAP RPC over :9653)
  └── response back to zip.Ctx.JSON() — same jsonenc, same variant
        ↓
gateway → ingress → external client

Invariants

  1. JSON happens at most ONCE per request, at the subsystem handler boundary. Inter-subsystem code paths use ZAP-typed Go values — cloud.Deps.IAM.VerifyJWT(...), cloud.Deps.Commerce.GetTenantConfig(...), etc. No subsystem marshals a struct, hands it to another subsystem, and watches it get unmarshaled.

  2. encoding/json/v2 is the canonical JSON impl. When the binary is compiled with GOEXPERIMENT=jsonv2, every JSON path in hanzoai/zip (and therefore every Hanzo HTTP handler) routes through stdlib encoding/json/v2. Without the flag, zip falls back to encoding/json v1. No third-party JSON library (goccy/go-json, sonic, jsoniter, …) is permitted in the Hanzo Go stack. Stdlib only.

  3. ZAP RPC is the wire format when subsystems are split-deployed. The same cloud.<Subsystem>Client interface that resolves to a direct Go call when co-resident resolves to a ZAP RPC client when split. The subsystem caller does not branch on the mode. Inter-subsystem RPC rides the existing :9653 ZAP listener.

  4. One JSON entry point per Hanzo Go binary. hanzoai/zip internal/jsonenc package; selected at compile time by goexperiment.jsonv2 build tag. zip.JSONVariant is a constant exposing which impl is active (encoding/json/v2 or encoding/json). zip.New logs it at startup so operators can confirm the impl from production logs.

  5. Brand-neutral. All hostnames, brands, and domain references are config-driven per the existing brand-package contract — no hanzo.ai hardcodes in the wire-stack logic. The same binary serves api.hanzo.ai, api.osage.cloud, api.lux.cloud, etc.

Inter-subsystem client wiring (cloud.Deps)

Per HIP-0106 "Subsystem-to-subsystem calls", cloud.Deps exposes typed clients (one per subsystem). cloud.BuildDeps(cfg) picks the implementation per subsystem:

Subsystem state Endpoint configured? Resolves to
Enabled in this process n/a nil — the subsystem's own Mount() installs its in-process Client
Disabled Yes (CLOUD_<NAME>_ZAP_ADDR) ZAP RPC client targeting the endpoint
Disabled No clients.Disabled<Name>() — fail-closed stub returning a clear error
Payments / Vault (always RPC per HIP-0106 solo-vault CDE) ZAP RPC client at CLOUD_PAYMENTS_ZAP_ADDR / CLOUD_VAULT_ZAP_ADDR, or fail-closed disabled stub if no endpoint

Subsystem code calls deps.<Name>.<Method>(...) without knowing the mode. The interface is the contract. Detection of the fail-closed stub at mount-time uses clients.IsDisabled(err).

The cloud/types leaf package holds the transport types AND the client interfaces so the in-process / RPC implementations can satisfy them without an import cycle through cloud. As subsystems ship their .zap schemas and zapc generate <schema>.zap --lang go --out ./zap/gen/ produces typed bindings, the placeholder types in cloud/types/ become aliases to the generated structs.

Canonical Hanzo Go stack

The unified binary is opinionated. Every subsystem uses the same Go substrate. One way to do everything. No parallel frameworks, no parallel ORMs, no parallel loggers, no parallel wire formats.

Concern Canonical Notes
Web framework hanzoai/zip The ONE Go web framework. Built on Fiber v3 / fasthttp (implementation detail). Sinatra/Express-style primary API. No .Fast escape hatch — zip is fast.
ORM hanzoai/orm Backends: SQLite (today), SQL/MySQL/MSSQL/Oracle via dbx (wiring pending), ZapDB via luxfi/database, CR-SQLite for client-side distributed (license-permitting).
Logger luxfi/log NEVER uber-go/zap, NEVER log/slog, NEVER stdlib log.
Wire protocol ZAP Every subsystem ships <svc>/schema/<name>.zap. zapc generates Go/TS/Py/Rust bindings. No .capnp files in Hanzo-authored source.
Storage durability hanzoai/replicate over hanzo/vfs Per HIP-0107 (streaming replication over vfs). Covers SQLite WAL, ZapDB log, blockchain state, generic logs through one pipeline.
Object store interface hanzo/vfs The ONLY object-store interface. All sink-side bytes route through vfs.
Analytical store hanzoai/datastore-go Separate from orm. NOT an ORM backend — different workload class.

Migration adapters (transitional only, not parallel ways to build new services): zip.AdaptNetHTTP(http.Handler), zip.AdaptNetHTTPFunc(http.HandlerFunc), zip.AdaptNetHTTPMiddleware(func(http.Handler) http.Handler), and app.Mount(prefix, http.Handler) as the path-prefixed mount form. chi.Router, gin.Engine, and beego.App.Handlers all satisfy http.Handler natively, so the same adapter covers every legacy framework — no per-framework wrapper needed. These exist so existing chi/beego/gin code can be wrapped into a zip mount without a same-day rewrite. New code must be written natively against zip. Adapters cost ~5% per-request perf versus native Fiber dispatch and that cost compounds at high RPS; replace adapted routes when feasible.

The framework itself is hanzoai/zip v0.1.0+ on feat/fiber-v3 (commit train rebuilds upstream zeekay/zip from scratch on Fiber v3; see hanzoai/zip PR #1). zip is the ONE web framework. chi / gin / beego / echo are MIGRATION-ONLY and never appear in new Hanzo Go code.

Process model

cloud is a single process exposing:

  • One HTTP listener (default :8080) that fans out to subsystem handlers by URL prefix (/v1/iam/..., /v1/base/..., etc.)
  • One ZAP RPC listener (default :9653) for service-to-service auth and inter-subsystem calls when split across binaries
  • One health/metrics endpoint at :9090
  • One admin endpoint at :8081 (gated by IAM admin role)

Subsystem activation:

cloud \
  --enable=iam,base,kms,commerce,gateway,ai,o11y \
  --brand=osage \
  --domain=osage.cloud \
  --iam-issuer=https://iam.hanzo.id \
  --kms-master-key-ref=kms://hanzo/cloud/osage/master \
  --data-dir=/var/lib/cloud

Each subsystem flag enables that subsystem's HTTP routes, ZAP services, and background workers. Disabled subsystems contribute zero runtime cost beyond the compiled code in the binary.

Subsystem boundaries

Each Hanzo Go service exposes a single Mount(app *zip.App, deps cloud.Deps) error function (canonical signature; the old chi.Router-based shape is migrated through the zip.AdaptChi adapter). cloud's main.go is essentially:

import (
    "github.com/hanzoai/zip"
    "github.com/hanzoai/iam"
    "github.com/hanzoai/base"
    "github.com/hanzoai/kms"
    "github.com/hanzoai/commerce"
    "github.com/hanzoai/ai"      // LLM control plane subsystem (was hanzoai/cloud pre-rename)
    "github.com/hanzoai/gateway"
    "github.com/hanzoai/o11y"
    "github.com/hanzoai/vfs"
    "github.com/hanzoai/mq"
    "github.com/hanzoai/dns"
    "github.com/hanzoai/amqp"
    "github.com/hanzoai/mcp"
    "github.com/hanzoai/cloud"
)

func main() {
    cfg := cloud.LoadConfig()
    deps := cloud.BuildDeps(cfg)
    app := zip.New()

    if cfg.Enabled("iam")      { iam.Mount(app, deps)      }
    if cfg.Enabled("kms")      { kms.Mount(app, deps)      }
    if cfg.Enabled("base")     { base.Mount(app, deps)     }
    if cfg.Enabled("commerce") { commerce.Mount(app, deps) }
    if cfg.Enabled("ai")       { ai.Mount(app, deps)       }
    if cfg.Enabled("gateway")  { gateway.Mount(app, deps)  }
    if cfg.Enabled("o11y")     { o11y.Mount(app, deps)     }
    if cfg.Enabled("vfs")      { vfs.Mount(app, deps)      }
    if cfg.Enabled("mq")       { mq.Mount(app, deps)       }
    if cfg.Enabled("dns")      { dns.Mount(app, deps)      }
    if cfg.Enabled("amqp")     { amqp.Mount(app, deps)     }
    if cfg.Enabled("mcp")      { mcp.Mount(app, deps)      }
    // ...

    cloud.Serve(app, cfg)  // HTTP + ZAP RPC + admin
}

This means every existing Go service must expose a Mount function in addition to its cmd/<service>/main.go. The main.go becomes a thin shim that calls Mount on its own; cloud's main calls the same Mount from its own binary. No business logic moves.

Realized refinement: the explicit if cfg.Enabled(...) enumeration above shipped as the registry pattern — cloud.Register(name, order, mount) from each subsystem's init() plus a blank import in cmd/cloud, with MountAll/ShutdownAll driving ordered mount and reverse-ordered teardown. See "Realized state" above. The Mount contract itself is unchanged.

Reference implementations already in tree (per AUDIT_2026_05_19.md): commerce, gateway, vfs — these export Mount(...) today. New subsystems join by mirroring their shape.

ZAP schema contract

Every subsystem ships a public .zap schema describing its in-process and over-wire interface. Build pipeline:

<subsystem>/
  schema/<name>.zap       # public typed interface
  zap/gen/                # zapc-generated bindings (Go for our use, others optional)
    <name>.go             # generated structs + interfaces
    <name>_server.go      # server-side handlers
    <name>_client.go      # typed client (in-process or RPC)
  Makefile / build.sh     # `zapc generate <schema>.zap --lang go --out ./zap/gen/`

zapc is the Rust-implemented Hanzo ZAP compiler at ~/work/hanzo/zap/zapc-rs/. Multi-language codegen: zapc generate file.zap --lang {go,ts,py,rust}.

When cloud runs subsystems in-process: each Mount(...) registers its *_server.go against the local ZAP dispatcher, and the typed client interfaces in deps resolve to direct Go function calls through the ZAP runtime (no marshalling, no network). When subsystems are split: same generated client makes ZAP RPC calls over the wire. Same business code in either mode.

Existing .zap schemas in production (real, not aspirational):

  • ~/work/hanzo/ai/ai.zap (was ~/work/hanzo/cloud/cloud.zap pre-rename) — LLM control plane types (ChatMessage, ModelProvider, ChatCompletion)
  • ~/work/hanzo/commerce/api/billing/billing.zap — billing schemas
  • ~/work/hanzo/tasks/schema/tasks.zap — task scheduling
  • ~/work/hanzo/zap/rust/schema/zap.zap — self-describing schema

Subsystems with generated bindings under <svc>/zap/: python-sdk/proto/zap, kv/modules/zap, playground/internal/zap, hanzo.ai/components/zap, platform/pkg/zap, mcp/dist/zap, dev/hanzo-dev/zap, docdb/internal/zap, vector/src/zap. At least 10+ subsystems already on the pattern.

Policy: no .capnp files. No "Cap'n Proto" identifiers in Hanzo-authored source. ZAP is Hanzo-native and is the only thing the public surface knows about. (Brand-policy parity with @hanzo/gui / Zen MoDE — see CLAUDE.md.)

Edge + stateless scaling

The cloud binary is fully stateless within the process. All state lives in the per-tenant SQLite + KMS + VFS layer per HIP-0302 / HIP-0107. Any replica can serve any request as long as it can open the requesting tenant's SQLite file from local storage (cached) or the encrypted S3 mirror (cold).

load balancer (k8s Service / DO LB / Cloudflare)
  └── sticky / consistent-hash on X-Org-Id
      ↓
┌──────────────┐  ┌──────────────┐  ┌──────────────┐
│ cloud replica│  │ cloud replica│  │ cloud replica│   ← N replicas, identical
│ ingress      │  │ ingress      │  │ ingress      │     binary, no shared
│ gateway      │  │ gateway      │  │ gateway      │     in-process state
│ iam, kms,    │  │ iam, kms,    │  │ iam, kms,    │
│ base,        │  │ base,        │  │ base,        │
│ commerce,    │  │ commerce,    │  │ commerce,    │
│ ai, vfs,     │  │ ai, vfs,     │  │ ai, vfs,     │
│ o11y, mcp,   │  │ o11y, mcp,   │  │ o11y, mcp,   │
│ amqp, mq,    │  │ amqp, mq,    │  │ amqp, mq,    │
│ dns, authz   │  │ dns, authz   │  │ dns, authz   │
└──────────────┘  └──────────────┘  └──────────────┘
       │                 │                 │
       └─────────────────┼─────────────────┘
                         ↓
        ┌──────────────────────────────────────┐
        │ per-tenant SQLite + age-encrypted     │
        │ S3 mirror (HIP-0302, HIP-0107).       │
        │ KMS master key + per-org HKDF DEK.    │
        │ VFS = canonical object-store iface.   │
        └──────────────────────────────────────┘

Routing

The load balancer routes external requests to any replica. Consistent-hash on X-Org-Id (after gateway-mint) keeps each tenant warm on one replica when possible — this is a perf optimization, not a correctness requirement. Cold tenants get served by whichever replica has capacity; per-tenant SQLite cold-open is millisecond-scale.

Gateway as edge subsystem

Within each replica, the gateway subsystem owns the edge concerns:

  • JWT validation against iam JWKS
  • Identity-header strip + gateway-minted X-Org-Id per iam.tenantClaim
  • Per-route policy + rate limiting

After gateway, calls between subsystems use ZAP-typed Go method calls (see "Subsystem boundaries"); no per-hop JSON marshalling. JSON marshal runs at most once per request, at the subsystem handler boundary, returning to the gateway response path.

Scaling characteristics

Workload RAM per replica Throughput per replica
Idle ~150 MB n/a
100 active tenants, mixed ~500 MB – 1 GB ~10K req/s
1000 active tenants, heavy ~7 – 16 GB ~50K req/s

Horizontal scaling knob: number of replicas behind the load balancer. Kubernetes HPA on CPU + per-replica X-Org-Id-affinity hashing scales linearly until the per-tenant SQLite + replicate fan-out hits its own limits, which sit well above this binary's per-replica throughput.

Cold-start budget: ~150 ms full boot with all 13 subsystems mounted; the lazy-mount pattern from HIP-0108 brings this down to ~10 ms by deferring subsystem Mount() until first request.

Per-replica capacity budget

The verified, measured budget for a Hanzo zip-on-fasthttp replica (Apple M1 Max / Go 1.26.3 / Fiber v3 v3.2.0, gateway hot-path):

Conns Heap delta Per-conn heap Goroutines
1,000 7.84 MiB 8.02 KiB 1.00 / conn
8,454 67 MiB 8.02 KiB 1.00 / conn
Concurrent conns Heap Pod RAM (with headroom)
10,000 80 MiB 256 MiB
100,000 800 MiB 1 GiB
1,000,000 8 GiB 10 replicas × 1 GiB

The operational target is 100k concurrent client connections per replica at a 1 GiB pod ceiling. The cliff above 100k/replica is OS-side (fasthttp listener queue, ulimit, kernel ephemeral port range), not Go-side. Cap zip.Config.Concurrency: 100_000 to stay inside the budget; the kernel ulimit must be configured accordingly via the pod's securityContext.

JSON impl at the edge: every production cloud Dockerfile compiles with GOEXPERIMENT=jsonv2. Verified edge-path wins on Apple M1 Max / Go 1.26 / zip on Fiber v3 v3.2.0:

Bench json/v1 json/v2 Δ
Edge POST roundtrip 19,782 ns / 73 allocs 17,406 ns / 56 allocs −12% time, −23% allocs
Marshal-only 12,860 ns / 34 allocs 10,092 ns / 34 allocs −22% time
Unmarshal-only 17,122 ns / 67 allocs 13,785 ns / 50 allocs −19% time, −25% allocs

JSON marshal runs at most once per request (at the gateway edge); inter-subsystem calls use ZAP. The −22% marshal-only win lands once, on the response path to the client.

Reproduce:

cd ~/work/hanzo/zip
go test -bench=BenchmarkJSON -benchmem -run=^$ .
GOEXPERIMENT=jsonv2 go test -bench=BenchmarkJSON -benchmem -run=^$ .

cd ~/work/hanzo/gateway
go test -mod=mod -run=TestConnMemory -v -conn-count=10000

Canonical scale doc: ~/work/hanzo/hips/docs/SCALE_STANDARD.md.

Single-process invariant

By design, the cloud binary holds no per-tenant state in process memory beyond:

  • the read-side page cache for SQLite (evictable, pragma cache_size-bounded)
  • the wazero/goja/pyvm extension runtime pools (HIP-0105, HIP-0108)
  • the in-process Deps-client method dispatch table

Replica restart is safe at any time. Active requests reconnect via the load balancer. No graceful-drain coordination required across replicas beyond standard k8s pod lifecycle.

Anti-patterns

  • Replica-local caches keyed by tenant ID without time-based eviction → causes memory leak under tenant churn
  • Cross-replica in-memory pub-sub (sharing state via NATS in-memory topics) → use durable queue subsystem (mq, amqp) instead
  • Sticky-session affinity REQUIRED (vs. preferred) → forces stateful load balancer config; breaks the "any replica serves any tenant" invariant. The X-Org-Id consistent hash is an optimization, not a contract.

Tenant isolation

Layer Today Under HIP-106
Auth Per-domain IAM (multi-tenant) Unchanged. IAM resolves (app, org) from origin; subsystems see JWT claims via X-Org-Id.
Storage Per-service postgres or per-tenant SQLite (varies) Always per-tenant SQLite ({data-dir}/orgs/{org}/{service}.db) with per-org DEK per HIP-0302. No postgres in the unified path.
KMS Per-org master keys today Unchanged. KMS in-process serves kms://<deployment>/<org>/<purpose> references.
Cache Per-service KV (varies) Process-local LRU or per-org sub-buckets in shared in-memory cache. No KV.
Brand Per-domain detection in app code cfg.Brand at startup; subsystems read brand from deps; UI templates resolved from embedded assets.

Subsystem-to-subsystem calls

In the unified binary, IAM, KMS, Base, Commerce, Cloud, etc. live in the same process address space. Inter-subsystem calls are ZAP-typed Go function calls via the deps:

type Deps struct {
    IAM        iamzap.Client       // generated from iam/schema/iam.zap
    KMS        kmszap.Client       // generated from kms/schema/kms.zap
    Base       basezap.Client      // generated from base/schema/base.zap
    Commerce   commercezap.Client  // generated from commerce/schema/commerce.zap
    Cloud      cloudzap.Client     // generated from cloud/schema/cloud.zap
    O11y       o11yzap.Client      // generated from o11y/schema/o11y.zap
    BrandCfg   brand.Config
}

Each generated Client has two implementations:

  • in-process (direct method calls through the local ZAP dispatcher)
  • RPC (ZAP-typed RPC over the wire)

cloud wires in-process. Legacy split deploys wire RPC. Same business code in either mode. Every subsystem boundary is typed end to end via the .zap schema.

Extension surface

User-supplied code inside the unified binary uses the in-process extension runtime from HIP-0105:

  • Per-record hooks in Base → goja (per HIP-0105 scale findings: goja wins multi-tenant SaaS at scale)
  • Per-request policy rules in Gateway → wazero (untrusted) or native (Hanzo-authored)
  • Custom prompt transforms for AI (LLM control plane subsystem) → wazero
  • Custom tool functions for Agents → wazero

The extension runtime IS the user-code boundary inside the unified process. Don't shell out, don't spawn sidecars, don't run Knative pods for per-request hooks. HIP-0060 (Functions) handles the workloads where those overheads are justified.

Multi-language handlers

HIP-0105 defines two mount points (in-process Base hooks AND web routes via hanzoai/zip). The unified binary uses mount point #2 to allow service routes themselves to be authored in any HIP-0105-supported language:

Language Runtime name Mount path
Go (Hanzo-authored) native direct in-process — default for all service code
Rust / C++ / Zig / AssemblyScript wasm (wazero) compiled to *.wasm, loaded under hz_routes/<name>/
JavaScript / TypeScript goja (production) or v8go (experimental) source files loaded directly
Python pyvm (single-tenant only, -tags pyvm) CPython 3.13 sub-interpreter pool
DSL / policy starlark sandboxed, deterministic, no I/O by default

Every HIP-0105 runtime is mountable as a route via the SAME entry point: app.Module(method+path, runtimeName, modulePath). One method on the zip.App; one canonical JSON envelope shape ({method, path, params, query, headers, body, org, user, userEmail}) every guest sees; one response envelope ({status, headers, body}) every guest returns. There is no per-runtime mount API — app.ModuleWasm / app.ModuleGoja / app.ModulePython do not exist on purpose. One way.

app.Module("POST /v1/policy/eval",  "wasm",     "./ext/policy")    // Rust/AS/Zig/C → wasm via wazero
app.Module("POST /v1/transform",    "pyvm",     "./ext/transform") // single-tenant CPython
app.Module("POST /v1/webhook",      "goja",     "./ext/webhook")   // recommended multi-tenant JS
app.Module("POST /v1/route",        "starlark", "./ext/route")     // config DSL

The route author writes their handler in their preferred language; the same .zap schemas generate the same I/O types across all of them. Crash isolation, cancellation semantics, and scale characteristics are exactly as described in HIP-0105. The loader is duck-typed via zip/runtime.Loader so zip itself stays decoupled from hanzoai/base/plugins/extruntime (the canonical loader implementation); the unified binary constructs *extruntime.Loader once with whichever runtimes it cares about and threads it into zip.Config.Loader.

Multi-tenant deployments MUST gate AllowedRuntimes on zip.Config to exclude runtimes lacking hard sandbox (pyvm, v8go). AllowedRuntimes: nil accepts whatever the Loader has registered.

API keys

The credential for programmatic access is an API key. IAM mints and verifies it, gateway resolves it to a principal at the edge, and no subsystem downstream reads it again. There are two types, and the prefix is what every consumer switches on:

Type Prefix Where it belongs
publishable pk- browser and client code; identifies an org, authorizes nothing that spends
secret sk- server side only; carries the caller's full scope

hk- is the older name for a secret key. Verification still accepts one; nothing has minted one since iam v1.33.9.

GET    /v1/keys    # the caller's keys: { type, prefix, createdAt }
POST   /v1/keys    # mint or rotate the key of { type }
DELETE /v1/keys    # revoke the key of that type

The secret is returned exactly once, at mint. Every later read returns type, prefix and creation time. What is stored is a hash of the key, never the key — a plaintext credential at rest is a defect, not a configuration choice. The subject a key is minted for is derived from the validated identity headers and never from the request body, so a caller can mint and revoke only their own.

A key carries a scope, and the scope is enforced at the gateway edge before any subsystem sees the request:

Field Meaning
models which models the key may address; * for all
services which subsystems it may invoke — llm, agents, mcp, embeddings, images, audio
rateLimit requests per minute; default 60
spendLimit ceiling in USD cents per billing period; unset means the org balance is the only ceiling
allowedIPs CIDR allowlist; unset means any address
expiresAt expiry; unset means the key lives until revoked

Credit metering

Spend is prepaid. An org buys credits and every priced request draws the balance down, so spend cannot exceed what was bought and there is no surprise bill. One credit is one US cent — the arithmetic and the display are the same unit. One balance covers every subsystem: inference, agent runs, MCP tool calls, storage.

commerce owns the balance. The metering client is the one place this binary asks about money, and it wraps every priced request in two calls:

  1. Authorize, before the handler runs. Sufficient balance passes. Insufficient balance is 402 insufficient_balance and the handler never runs. An unreachable commerce is 503 balance_unavailable.
  2. Record, after the handler returns, with the units the request actually consumed.

Fail-closed is the default: when commerce cannot be reached the request is denied rather than served unpriced. Fail-open is a deliberate per-deployment choice, never the consequence of an outage. Free routes declare a price of zero and skip both calls.

A usage event says who spent, what served it, what it consumed and how it went. It carries no prompt content and no PII.

type UsageEvent struct {
    ID        string
    Timestamp time.Time

    // Who spent
    OrgID     string
    ProjectID string
    UserID    string
    KeyID     string

    // What served it
    Service  ServiceScope
    Model    string
    Provider string // the upstream that actually answered

    // What it consumed
    PromptTokens     int
    CompletionTokens int
    TotalTokens      int
    Cost             int64 // USD cents

    // How it went
    LatencyMs int64
    TTFTMs    int64 // time to first token, streaming
    Status    UsageStatus

    // Agent runs attribute each tool call separately
    AgentID    string
    AgentRunID string
    ToolCalls  []ToolCall

    Metadata map[string]string
}

type ToolCall struct {
    Name       string // tool
    Provider   string // MCP server that served it
    DurationMs int64
    Status     UsageStatus
}

Events are written to the calling tenant's own store, so a usage read is org-scoped by construction rather than by a WHERE clause, and commerce aggregates them for invoicing and reseller revenue share.

GET /v1/usage/summary       # current billing period
GET /v1/usage/timeseries    # hourly, daily or monthly buckets
GET /v1/usage/by-model
GET /v1/usage/by-user
GET /v1/usage/by-key
GET /v1/usage/events        # paginated raw events

All six accept start, end, granularity and filter. An alert is the same data read against a threshold — spend, request count or error count, over a daily, weekly or monthly period — delivered to a webhook, an email address or a Slack hook when it is crossed.

OpenAI-compatible surface

The inference surface is OpenAI's, so an existing application moves by changing two strings:

from openai import OpenAI

client = OpenAI(
    api_key="sk-...",
    base_url="https://api.hanzo.ai/v1",
)

response = client.chat.completions.create(
    model="zen-8b-instruct",
    messages=[{"role": "user", "content": "Hello"}],
)
POST /v1/chat/completions      # streaming and non-streaming
POST /v1/completions           # legacy
POST /v1/embeddings
POST /v1/images/generations
POST /v1/audio/transcriptions
POST /v1/audio/translations
GET  /v1/models

The ai subsystem holds the model catalog and the routing policy; gateway speaks the OpenAI shape at the edge and absorbs provider-specific differences. Both are subsystems of this binary, so a request arriving at /v1/chat/completions is authenticated, authorized against the balance, routed, served and recorded without leaving the process.

Deployment surfaces this enables

Deployment Brand Enabled subsystems Domain
Hanzo flagship hanzo all api.hanzo.ai
Osage Cloud osage iam, base, kms, commerce, ai, gateway, o11y, vfs api.osage.cloud
Lux Cloud lux iam, base, kms, gateway, chain api.lux.cloud
Zoo Cloud zoo iam, base, kms, ai, gateway, vfs api.zoo.cloud
Customer X (reseller) custom iam, base, kms, commerce, gateway api.x.com

Same image. Different startup configuration. The osage.cloud marketing site that shipped 2026-05-19 gets a real backend when this HIP lands.

Migration plan

Multi-week real engineering. Order revised from AUDIT_2026_05_19.md findings:

Phase 1 — Mount contract on reference + smallest services (1 week)

Per AUDIT_2026_05_19.md, three subsystems already export Mount(...): commerce, gateway, vfs. These are the reference impls — Phase 1 first reshapes their signatures to the canonical (*zip.App, Deps) error form, then extends the same shape to the smallest remaining services:

Reference impls (already Mount-shaped):

  1. commerce — production, multi-tenant (37 X-Org-Id call-sites), IAM-integrated, Mount exists. Reshape Deps to the canonical interface and use it as the live blueprint.
  2. gateway — Mount exists. Validate that the subsystem can be both standalone and embedded.
  3. vfs — Mount exists. Smallest of the three.

Smallest remaining services to bring to the Mount contract:

  1. kms — smallest service still needing Mount; clean deps.
  2. dns — small, no auth dep.
  3. amqp — small, no auth dep.
  4. authz — first to consume deps.IAM.

Explicitly excluded from Phase 1 (and from the unified binary entirely):

  • vault — PCI-CDE. Folding it into a multi-tenant process expands PCI scope to every other tenant. Stays its own deployment. See Non-goals.

Phase 2 — Ship cloud (1 week)

~/work/hanzo/cloud/cmd/cloud/main.go — new repo github.com/hanzoai/cloud. Imports the seven subsystems from Phase 1, wires Deps, dispatches by subsystem flag. Ship as ghcr.io/hanzoai/cloud:v0.1.0. Single-tenant smoke deployment at a dev domain first.

Phase 3 — Fold the heavy subsystems (2 weeks)

  1. iam — has its own SPA; mount handlers without changing SPA
  2. base — plugins/extruntime, plugins/jsvm, plugins/wasmvm must remain isolated per-org (per HIP-0105)
  3. o11y — heaviest multi-tenant footprint (309 X-Org-Id call-sites per audit). Get this right and the per-tenant routing pattern is proven for everything else.
  4. ai (LLM control plane) — mount existing routes
  5. mcp — depends on iam
  6. mq — depends on base for durability
  7. ingress — depends on gateway routes

Phase 4 — Tenant routing layer (1 week)

Universal X-Org-Id gating at the unified mux entry. Per-tenant data isolation enforced by Base. KMS reference resolution scoped to the calling org. Telemetry tagged with org.

Phase 5 — Reseller provisioning + operator convergence (1 week)

Operator CRD ResellerCloud{name, parentOrg, brand, enabledSubsystems} that creates the IAM app + KMS namespace + Base storage allocation + Gateway routes atomically. Documented at ~/work/hanzo/cloud/docs/RESELLER.md. Self-serve resell becomes possible.

Operator convergence (BLOCKER for Phase 5). The audit identified three parallel operator lineages:

  • ~/work/hanzo/operator (Go)
  • ~/work/hanzo/hanzo-operator (Go, production)
  • ~/work/hanzo/operator-core (Rust)

Phase 5 cannot ship until one is picked and the other two are either folded in or archived. Recommended path: keep hanzo-operator (the production lineage with the existing ClusterRole), fold the ResellerCloud CRD into it, archive operator/, and demote operator-core to a Rust library (library-no-action per audit) for shared CRD types. Decision required before Phase 5 starts.

Phase 6 — Billing wiring (separate HIP follow-up)

Commerce subsystem reads per-tenant usage from base + o11y/Datastore and applies the reseller revenue-share contract. commerce is the canonical billing/pricing/subscription home — the TS billing and pricing packages get absorbed into commerce via Go rewrites.

Note on auto: the earlier audit grouped auto with billing/pricing for commerce absorption. This was wrong. ~/work/hanzo/auto is a plug-n-play IFTT-style trigger framework that sits on top of ~/work/hanzo/tasks (durable task queue). It is NOT under commerce. auto is its own subsystem and mounts independently. tasks is its own subsystem — the durable-queue primitive used by auto, by commerce recurring billing, by o11y retention jobs, and by anything else that needs durable scheduling.

Commerce — light router, NOT in PCI-DSS scope

Commerce is a thin orchestrator. It owns the customer-facing checkout flow, tenant config, billing logic, pricing logic, invoicing, and webhook intake. It explicitly does NOT:

  • Touch a Primary Account Number (PAN)
  • Process card data
  • Implement processor connector logic (native PSP SDK / Adyen SDK)
  • Store encrypted PAN

Commerce only handles tokens (vault tokens) and intents (payments-orchestrator references). When commerce needs to charge, it calls payments (Rust) via ZAP RPC with a token + amount + processor hint. Payments calls vault (Go) via ZAP RPC with a "Charge this token" request; vault pulls the PAN from its encrypted store, makes the outbound HTTPS to the processor, and returns the response. PAN never leaves vault.

This makes commerce CDE-connected, not CDE. Lighter controls apply (network segmentation, access control, change management) but commerce is NOT subject to PCI-DSS L1 audit.

Solo-vault CDE

Vault is the only system in PCI-CDE. Per the corrected scope:

System PCI scope
vault CDE — the only system that touches PAN. Full L1 audit. Quarterly ASV. HSM-backed key store. Own deployment, own k8s namespace, own NetworkPolicy boundary.
payments CDE-connected (NOT CDE). Sees only tokens. Payments service operated in tokens-only mode. Calls vault.Charge(token, processor, amount) for the actual processor call.
commerce CDE-connected (NOT CDE). Light router. Only ever handles tokens + intent IDs. Mounts inside cloud like any other subsystem.
Everything else in cloud Not CDE-connected. Standard SOC2-grade controls.

For this architecture to be sound, two requirements must hold:

  1. Browser-side card collection runs directly against vault (vault ships a vault-collect.js iframe; PAN posts directly to vault from the browser, never via commerce or any Hanzo app server).
  2. Payments runs in tokens-only mode — verified by audit of payments data flow that no code path exposes raw PAN to the surrounding Go process.

Both are tracked under the implementation TODO list at ~/work/hanzo/vault/docs/ (to be created).

PSP optionality

The same architecture supports four deployment modes:

  1. Default (Hanzo as merchant): Hanzo operates vault + payments + commerce. Hanzo bears the PCI-DSS L1 audit. PCI scope = vault only.

  2. Hanzo as PSP for a white-label customer: customer's brand (lux.cloud, zoo.cloud, osage.cloud) runs commerce inside their cloud deployment; commerce's payments_client and vault_client ZAP endpoints point at Hanzo's payments + vault. Customer carries no PCI obligation. Hanzo's vault has multi-tenant token namespacing per org.

  3. Customer brings their own PSP backend: customer deploys their own vault + payments. Their cloud's commerce subsystem points its ZAP-RPC endpoints at THEIR vault + payments deployment. Hanzo carries no PCI obligation for that customer's flows. The customer holds their own PCI scope. Commerce is a swappable thin router.

  4. Single-tenant Hanzo Payments-as-a-product: customer's ENTIRE commercial unit is payment-processing. Deploy payments + vault + a trimmed cloud as a unit. Commerce still operates as light router — no design change, only deployment shape.

Modes 1-3 share the same binary. Configuration determines which endpoints commerce talks to. The "swappable thin router" property is load-bearing: commerce never grows code that depends on a specific vault or payments operator.

Non-goals

  • TS service rewrite as part of this HIP. Platform (Next.js / Dokploy fork), brain (where still TS), bot, billing, pricing (separate Go rewrites slated under commerce subsumption). They can be ported to Go later if performance or operations require it; this HIP does not block on them.
  • vault and payments are explicitly NOT folded. Both stay as their own deployments with their own PCI scope boundaries per the "Solo-vault CDE" section above. Vault is CDE. Payments is CDE-connected. Commerce talks to both via ZAP RPC. Hard rule, no exceptions — even single-tenant deployments use the three-process architecture.
  • ~/work/hanzo/flow (Hanzo Flow — visual ML pipeline / agent-building) is NOT folded. Visual ML pipeline / agent-building tool. Heavy native deps (torch, faiss, sentence-transformers). Runs as a separate process behind the gateway subsystem. Per the FT audit (2026-05-19), classified RED — defer to GIL-Python until torch ships cp313t (>=2.6).
  • ~/work/hanzo/datastore (Datastore fork) is NOT folded. OLAP column store. Uses Datastore-native ReplicatedMergeTree + S3 disk. Out of scope. Shares S3 bucket with HIP-0107 streaming via vfs prefix (s3://bucket/datastore/... vs s3://bucket/replicate/...).
  • ~/work/hanzo/insights (Hanzo Insights — AI observability + eval + prompt management) is NOT folded. Runs as a separate process — the canonical AI console for cloud-hosted LLM operations. Integrates with cloud via HTTP + (forthcoming) ZAP-typed endpoints; consumed by the cloud subsystem (LLM control plane) and surfaced to operators as part of the AI console.
  • Other Python services flagged RED by the 2026-05-19 free-threading audit (cli, erp, insights, sentry, studio) — all stay separate processes until their upstream FT-blockers clear (xmlsec, confluent-kafka, chdb, single-threaded Django/Celery assumptions, torch <2.6). Run under regular python3.13 (GIL-enabled) until then.
  • Cross-deployment service mesh. The unified binary collapses in-deployment service calls; cross-deployment (Hanzo ↔ Lux ↔ Zoo) stays on the existing service-discovery + bridge layer.
  • Auto-scaling per-subsystem. All subsystems in one binary scale together. If a subsystem becomes a hot bottleneck, fall back to running it as its own binary alongside the unified one — the Mount contract supports both.

Open questions

  1. Cold start under load — single binary with all subsystems boots slower than a focused service. Acceptable for long-lived deployments; needs measurement for fast-restart scenarios. Suggest benchmarking on Phase 2.

  2. Per-subsystem memory budgets — one OOM kills every subsystem. Acceptable trade-off for resell where blast radius is per-customer anyway, but Hanzo flagship may want to keep some subsystems split.

  3. Routes that conflict — /v1/iam/..., /v1/base/..., /v1/commerce/..., etc. Already mostly per-subsystem-prefixed. The unified mux compiles a route table at startup and refuses to start on collision.

  4. Build-time flags vs runtime flags — for production we want every subsystem compiled in. For developer builds we might want to disable some at build time to shrink the binary. ANSWERED by HIP-0116: neither build tags nor bigger binaries — services build standalone AND as ZAP-native plugin VMs (luxfi/lpm-installed, dispatched over ZAP per HIP-0114). Build tags are explicitly rejected there; runtime enablement stays the CLI/env flags specified here.

  5. ZAP versioning — when a subsystem evolves its .zap schema, how do we manage cross-version compat? Suggest semver on the .zap file itself (@version 1.2.0 directive) and zapc refusing breaking changes without an explicit major bump. Tracked for follow-up.

  6. Three competing operator lineages — operator/, hanzo-operator/, operator-core/ (Rust). Audit flagged for convergence. Phase 5 (reseller provisioning) is blocked on picking one. Suggest dedicated session for the operator decision before Phase 5 starts.

References

  • Reference: Discord (single binary serving all microservices), Tailscale (one tailscaled), GitLab (omnibus)
  • ~/work/hanzo/AUDIT_2026_05_19.md — ecosystem audit driving the migration order
  • HIP-0014 — Application Deployment Standard (per-service binaries today)
  • HIP-0026 — IAM (unified auth across the deployment)
  • HIP-0027 — KMS (unified secrets store)
  • HIP-0105 — In-Process Extension Runtime (the user-code substrate inside the unified binary)
  • HIP-0010 — Model Context Protocol Integration Standards (the MCP subsystem inside the binary)
  • HIP-0301 — Agent Runtime Protocols & Cross-Platform Parity (agents subsystem must satisfy)
  • HIP-0302 — Hanzo Replicate: Encrypted SQLite + ZapDB Durability for Base Services (the per-tenant data isolation model — covers both Base's SQLite backend AND ZapDB-backed deployments)
  • HIP-0107 — Streaming Replication over VFS (the unified streaming pipeline; supersedes the per-backend sink code in HIP-0302's reference impl — substrate stays, transport unifies)
  • HIP-0029 — Relational Database Standard (SQLite-primary per-tenant storage — the realized default)
  • HIP-0018 / HIP-0422 — payment processing / billing (the metering + balance-floor semantics gated at this binary's edge)
  • HIP-0114 — ZAP — Inter-VM Cognitive Transport (envelope, framing, authentication for the ZAP contract this HIP mandates)
  • HIP-0116 — Hanzo Plugin & VM Model (how subsystems take shape: standalone / embedded / plugin VM; answers Open Question 4)
  • HIP-0117 — Cloud-in-a-Box — One Binary, Three Modes (deployment topologies of this binary)