Files
skills/public/hip-0138.html

665 lines
68 KiB
HTML
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<!doctype html>
<html lang="en"><head>
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
<title>hip-0138</title>
<meta name="color-scheme" content="dark">
<style>
/* Committed to one visual world: a dark instrument panel. No light variant —
the dot field and the hairline rules only read on black, and a naive
inversion would wash both out. Every colour is painted explicitly so the page
never borrows a host background. */
@font-face{font-family:'Zen';src:url('/fonts/Zen-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen';src:url('/fonts/Zen-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Pixel Square';src:url('/fonts/ZenPixel-Square.woff2') format('woff2');font-style:normal;font-display:swap}
:root{
--ink:#f4f4f2; --soft:#9c9c98; --faint:#6a6a66; --ground:#000; --panel:#0a0a0a;
--line:#232323; --line-hi:#3a3a3a; --accent:#f4f4f2;
--font-zen-sans:'Zen',-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif;
--font-zen-mono:'Zen Mono',ui-monospace,"SF Mono",SFMono-Regular,Menlo,Consolas,monospace;
--font-zen-pixel-square:'Zen Pixel Square',monospace;
--mono:var(--font-zen-mono);
--sans:var(--font-zen-sans);
/* Controls are pills and surfaces are soft, as on hanzo.ai. */
--r:999px; --r-soft:14px;
}
*{box-sizing:border-box}
html{-webkit-text-size-adjust:100%}
body{margin:0;background:var(--ground);color:var(--ink);font-family:var(--sans);
font-size:16px;line-height:1.65;-webkit-font-smoothing:antialiased}
.wrap{max-width:60rem;margin:0 auto;padding:0 1.75rem}
/* The dot field. A halftone made of one repeating radial-gradient, faded out
along the diagonal by a mask so it reads as a wave rather than wallpaper. */
/* No overflow clip here: the dot field is inset to the box already, and a clip
would cut off the copy-prompt menu. */
.hero{position:relative;border-bottom:1px solid var(--line)}
.hero::before{content:"";position:absolute;inset:0;
background-image:radial-gradient(var(--line-hi) 1px, transparent 1px);
background-size:7px 7px;
-webkit-mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
pointer-events:none}
.hero .wrap{position:relative;padding-top:5.5rem;padding-bottom:4rem}
nav{border-bottom:1px solid var(--line)}
nav .in{max-width:60rem;margin:0 auto;padding:1.1rem 1.75rem;display:flex;
justify-content:space-between;align-items:center;gap:1rem}
.brand{font-family:var(--mono);font-size:.85rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--ink);text-decoration:none;
display:inline-flex;align-items:center;gap:.6rem}
.brand i{font-style:normal;color:var(--faint)}
.mark{width:1.15em;height:1.15em;display:block;flex:0 0 auto}
nav a.up{font-family:var(--mono);font-size:.72rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--soft);text-decoration:none}
nav a.up:hover{color:var(--ink)}
h1{font-family:var(--mono);font-size:clamp(2rem,5.4vw,3.4rem);line-height:1.12;
letter-spacing:-.02em;margin:0 0 1.1rem;font-weight:500;text-wrap:balance}
h1 em{font-style:normal;color:var(--faint)}
.lede{color:var(--soft);font-size:1.05rem;max-width:52ch;margin:0 0 2.25rem}
.btns{display:flex;flex-wrap:wrap;gap:.7rem;margin:0 0 .5rem;align-items:center}
.btn{display:inline-flex;align-items:center;gap:.5rem;font-family:var(--mono);
font-size:.72rem;letter-spacing:.14em;text-transform:uppercase;
padding:.8rem 1.4rem;border:1px solid var(--line-hi);border-radius:var(--r);
color:var(--ink);text-decoration:none;background:transparent;cursor:pointer;
line-height:1.2;font-weight:400}
.btn:hover{background:#141414;text-decoration:none;border-color:var(--soft)}
.btn.solid{background:var(--ink);color:#000;border-color:var(--ink)}
.btn.solid:hover{background:#d8d8d4}
.btn .chev{width:.7em;height:.7em;flex:0 0 auto;transition:transform .15s ease}
.btn[aria-expanded="true"] .chev{transform:rotate(180deg)}
/* Copy-prompt selector. Each row copies the prompt for its own target. */
.copy{position:relative;display:inline-flex}
.menu{position:absolute;top:calc(100% + .5rem);left:0;z-index:20;min-width:21rem;
background:var(--panel);border:1px solid var(--line-hi);border-radius:var(--r-soft);
padding:.4rem;display:flex;flex-direction:column;
box-shadow:0 12px 32px rgba(0,0,0,.75)}
.menu[hidden]{display:none}
.mi{display:flex;align-items:center;gap:.7rem;width:100%;text-align:left;
padding:.62rem .8rem;border:0;border-radius:calc(var(--r-soft) - .35rem);
background:transparent;color:var(--ink);font-family:var(--mono);font-size:.76rem;
letter-spacing:.04em;text-decoration:none;cursor:pointer;line-height:1.3;
white-space:nowrap}
.mi:hover,.mi:focus-visible{background:#181818;outline:none}
.mi .mark{width:1.05rem;height:1.05rem;color:var(--soft)}
.mi:hover .mark{color:var(--ink)}
.mi u{margin-left:auto;color:var(--faint);text-decoration:none;font-size:.68rem;
letter-spacing:.1em;text-transform:uppercase}
/* Works-with bar: one scrolling row, name and mark per agent. */
.strip{border-bottom:1px solid var(--line);background:var(--panel)}
.strip .in{max-width:60rem;margin:0 auto;padding:.9rem 1.75rem;display:flex;
align-items:center;gap:1.25rem;font-family:var(--mono);font-size:.72rem;
letter-spacing:.1em;text-transform:uppercase;color:var(--faint)}
.strip b{color:var(--soft);font-weight:400;flex:0 0 auto;
border-right:1px solid var(--line);padding-right:1.25rem;align-self:stretch;
display:flex;align-items:center}
.bar{display:flex;align-items:center;gap:.5rem;flex:1 1 auto;min-width:0;
overflow-x:auto;scrollbar-width:none;scroll-snap-type:x proximity;
-webkit-overflow-scrolling:touch;
-webkit-mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent);
mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent)}
.bar::-webkit-scrollbar{display:none}
.agent{display:inline-flex;align-items:center;gap:.45rem;flex:0 0 auto;
padding:.4rem .85rem;border:1px solid var(--line);border-radius:var(--r);
color:var(--soft);white-space:nowrap;scroll-snap-align:start;
text-decoration:none;background:var(--ground)}
.agent:hover{color:var(--ink);border-color:var(--line-hi);text-decoration:none}
.agent .mark{width:.95rem;height:.95rem}
h2{font-family:var(--mono);font-size:1.1rem;letter-spacing:-.01em;margin:2.75rem 0 .75rem;font-weight:500}
h3{font-size:1rem;margin:2rem 0 .5rem;font-weight:600}
h4,h5,h6{font-size:.94rem;margin:1.5rem 0 .5rem;font-weight:600}
p{margin:0 0 1rem;max-width:70ch}
ul,ol{margin:0 0 1rem;padding-left:1.35rem;max-width:70ch}
li{margin:.22rem 0}
a{color:var(--ink);text-decoration:underline;text-underline-offset:3px;
text-decoration-color:var(--line-hi)}
a:hover{text-decoration-color:var(--ink)}
a:focus-visible{outline:1px solid var(--ink);outline-offset:3px}
code{font-family:var(--mono);font-size:.85em;background:var(--panel);
border:1px solid var(--line);border-radius:5px;padding:.1em .36em}
pre{background:var(--panel);border:1px solid var(--line);padding:1rem 1.1rem;
border-radius:var(--r-soft);overflow-x:auto;margin:0 0 1.25rem}
pre code{background:none;border:0;padding:0;font-size:.82rem;line-height:1.7}
blockquote{margin:0 0 1rem;padding-left:1rem;border-left:1px solid var(--line-hi);color:var(--soft)}
hr{border:0;border-top:1px solid var(--line);margin:2.5rem 0}
table{border-collapse:collapse;width:100%;margin:0 0 1.25rem;font-size:.92rem;
display:block;overflow-x:auto}
th,td{border:1px solid var(--line);padding:.5rem .7rem;text-align:left}
.curl{display:block;background:var(--panel);border:1px solid var(--line);
border-radius:var(--r-soft);padding:.95rem 1.1rem;font-family:var(--mono);
font-size:.8rem;color:var(--soft);overflow-x:auto;margin:0 0 2.5rem;
white-space:pre;line-height:1.9}
.curl b{color:var(--ink);font-weight:400}
.curl i{font-style:normal;color:var(--faint)}
/* index */
#q{width:100%;padding:.85rem 1.2rem;font-family:var(--mono);font-size:.85rem;color:var(--ink);
background:var(--panel);border:1px solid var(--line);border-radius:var(--r);margin:0 0 .6rem}
#q::placeholder{color:var(--faint);text-transform:uppercase;letter-spacing:.1em;font-size:.72rem}
#q:focus{outline:none;border-color:var(--soft)}
#count{color:var(--faint);font-family:var(--mono);font-size:.72rem;letter-spacing:.1em;
text-transform:uppercase;margin:0 0 2rem}
.cat{margin:2.5rem 0 .5rem;font-family:var(--mono);font-size:.7rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);border-bottom:1px solid var(--line);
padding-bottom:.45rem}
.row{display:block;padding:.6rem .9rem;margin:0 -.9rem;border-bottom:1px solid var(--line);
border-radius:var(--r-soft);text-decoration:none}
.row:hover{background:#0a0a0a}
.nm{font-family:var(--mono);font-size:.84rem;color:var(--ink);display:block}
.ds{color:var(--soft);font-size:.9rem;display:block;margin-top:.12rem}
footer{margin-top:4rem;padding:2rem 0 4rem;border-top:1px solid var(--line);
color:var(--faint);font-size:.85rem}
footer a{color:var(--soft)}
.fmap{display:grid;gap:1.75rem;grid-template-columns:repeat(auto-fit,minmax(11rem,1fr));
margin:0 0 2rem;font-size:.85rem}
.fmap b{display:block;font-family:var(--mono);font-size:.68rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);font-weight:400;margin:0 0 .6rem;
border-bottom:1px solid var(--line);padding-bottom:.4rem}
.fmap a{display:inline-block;color:var(--ink);text-decoration:none;margin:.3rem .35rem 0 0}
.fmap a:hover{text-decoration:underline}
.fmap div{color:var(--faint);line-height:1.5}
.fend{border-top:1px solid var(--line);padding-top:1.25rem;font-size:.82rem}
@media (max-width:640px){
.hero .wrap{padding-top:3.25rem;padding-bottom:2.75rem}
.btns{gap:.5rem}
.btn{padding:.75rem 1.15rem;font-size:.68rem}
.copy,.copy .btn{width:100%;justify-content:center}
.menu{left:0;right:0;min-width:0}
.strip .in{flex-direction:column;align-items:flex-start;gap:.6rem;padding:.9rem 1.75rem}
.strip b{border-right:0;padding-right:0}
.bar{width:100%}
}
</style>
<link rel="alternate" type="text/markdown" href="/hip-0138.md">
<link rel="icon" href="/favicon.svg">
<link rel="canonical" href="https://hanzoskills.com/hip-0138">
</head>
<!-- Reading this with a machine? Every page here is also plain markdown.
This one: https://hanzoskills.com/hip-0138.md
Index: https://hanzoskills.com/llms.txt
Corpus: https://hanzoskills.com/all.md
Append .md to any path for the markdown twin. -->
<body>
<nav><div class="in">
<a class="brand" href="/"><svg class="mark" viewBox="0 0 67 67" fill="currentColor" aria-hidden="true"><path d="M22.21 67V44.6369H0V67H22.21Z"/><path d="M66.7038 22.3184H22.2534L0.0878906 44.6367H44.4634L66.7038 22.3184Z"/><path d="M22.21 0H0V22.3184H22.21V0Z"/><path d="M66.7198 0H44.5098V22.3184H66.7198V0Z"/><path d="M66.7198 67V44.6369H44.5098V67H66.7198Z"/></svg> HANZO<i>SKILLS</i></a>
<a class="up" href="/">All skills</a>
</div></nav>
<div class="wrap">
<h1>hip-0138</h1><p class="lede">HIP-138: Cloud — Unified Hanzo Binary. Status Final. Hanzo&#x27;s own standard — read this before implementing against it.</p><h1>HIP-0138: Cloud — Unified Hanzo Binary</h1>
<p><em>This document was numbered HIP-0106. That number is the plugin contract&#x27;s — HIP-0116 and the code both cite it that way — so this one took the next free number in its block.</em></p>
<h2>Abstract</h2>
<p>This proposal defines <code>cloud</code> — 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 <code>api.hanzo.ai</code>, <code>api.osage.cloud</code>, <code>api.lux.cloud</code>, <code>api.zoo.cloud</code>, 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.</p>
<p><strong>Naming note (2026-05-19 rename)</strong>: the unified binary lives at <code>hanzoai/cloud</code> (this repo); the former LLM-control-plane content that used to live at <code>hanzoai/cloud</code> was renamed to <code>hanzoai/ai</code> and is now mounted as the <code>ai</code> subsystem inside this binary. <strong>White-label fork target is <code>hanzoai/cloud</code></strong> — customers fork this one repo to launch their own ecosystem.</p>
<p><strong>Inter-subsystem contract</strong>: ZAP (the Hanzo native binary protocol). Every subsystem ships its public interface as a <code>.zap</code> schema; <code>zapc</code> generates Go/TS/Python/Rust bindings; <code>cloud</code> wires the in-process ZAP-typed Go interfaces when subsystems are co-resident, falls back to ZAP RPC over the wire when split. <strong>No <code>.capnp</code> files anywhere in Hanzo-authored code.</strong></p>
<p><strong>Transport boundary — ZAP only, day one.</strong> Every Hanzo-authored transport AND data type is ZAP. There is <strong>no gRPC and no protobuf anywhere in Hanzo-authored code</strong> — zero <code>google.golang.org/grpc</code>, zero <code>google.golang.org/protobuf</code>, zero <code>.proto</code>, zero <code>.pb.go</code>. The only historical gRPC was dead Temporal-porting codegen, removed in <code>hanzoai/tasks#12</code>. Where an external standard must be spoken at the interop edge (OpenTelemetry <strong>OTLP</strong> for trace/log ingest, <strong>OpAMP</strong> for agent management), the protobuf wire is produced by the <strong><code>zap</code> tooling</strong> — <code>pb2zap</code> converts the external <code>.proto</code> to a <code>.zap</code> schema (compiled by <code>zapc</code> to ZAP-native Go types), and <code>zap2pb</code> marshals those ZAP structs back to protobuf wire bytes at the boundary. Hanzo code holds only ZAP types and calls the generated converter; <strong>protobuf lives exclusively inside the <code>~/work/zap</code> converter tool, never in a Hanzo service.</strong> Transitive protobuf pulled by foundational dependencies (beego/authz/coraza/lego/otel, and even <code>luxfi/metric/client</code>) is a dependency-side follow-up, not Hanzo-authored code.</p>
<h2>Motivation</h2>
<p>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 <strong>white-label resell</strong> (<code>lux.cloud</code>, <code>zoo.cloud</code>, <code>osage.cloud</code>, and others) it&#x27;s not: every customer needs the same constellation of services, isolated per-tenant, billed per-tenant, auth&#x27;d against unified IAM. Shipping 11+ binaries × N customers × 3 environments multiplies operational surface beyond what a small team should run.</p>
<p>The audit at <code>~/work/hanzo/AUDIT_2026_05_19.md</code> confirms ~35 Go-native services structurally ready for inclusion, of which <strong>3 already export <code>func Mount(r, deps)</code></strong> — <code>commerce</code>, <code>gateway</code>, and <code>vfs</code>. These are the reference implementations.</p>
<p>The unified binary collapses this:</p>
<ol><li><strong>One artifact</strong>, <code>ghcr.io/hanzoai/cloud:vX.Y.Z</code>, that contains</li></ol>
<p> every Hanzo Go subsystem as compiled code.</p>
<ol><li><strong>Deployment configuration</strong> at startup enables a subset of subsystems</li></ol>
<p> (<code>cloud --enable=iam,base,kms,commerce,gateway,ai</code>).</p>
<ol><li><strong>Per-tenant routing</strong> at request time: <code>X-Org-Id</code> from JWT picks</li></ol>
<p> the tenant&#x27;s Base instance, KMS namespace, IAM application, and brand.</p>
<ol><li><strong>Multi-tenant Base</strong> at the storage layer per HIP-0302: each tenant</li></ol>
<p> org gets its own per-tenant data file (<code>data/{orgSlug}.db</code> for the SQLite backend, equivalent path for the ZapDB backend) with a per-org HKDF-derived DEK from a master key in KMS. <strong>Replicate works for both backends</strong> — SQLite WAL streaming and ZapDB-native log shipping use the same age-encrypted GCS bucket sink. Already the pattern in <code>~/work/hanzo/iam</code> and <code>~/work/hanzo/base</code>; this HIP makes it the universal contract.</p>
<ol><li><strong>Unified IAM auth</strong> at the boundary per HIP-0026: every subsystem</li></ol>
<p> trusts JWTs from one shared <code>iam.hanzo.id</code> JWKS endpoint. Gateway strips client-supplied identity headers, mints validated ones from the JWT, forwards in-process.</p>
<ol><li><strong>ZAP-typed interfaces</strong> between subsystems. Same generated Go code</li></ol>
<p> serves both in-process direct calls and over-wire RPC. Bootnode and other subsystems already use this pattern via <code>zapc</code> (the Hanzo ZAP compiler, Rust impl at <code>~/work/hanzo/zap/zapc-rs/</code>) today.</p>
<h2>Specification</h2>
<h3>Wire protocol stack</h3>
<p>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.</p>
<pre><code>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</code></pre>
<h4>Invariants</h4>
<ol><li>**JSON happens at most ONCE per request, at the subsystem</li></ol>
<p> handler boundary.** Inter-subsystem code paths use ZAP-typed Go values — <code>cloud.Deps.IAM.VerifyJWT(...)</code>, <code>cloud.Deps.Commerce.GetTenantConfig(...)</code>, etc. No subsystem marshals a struct, hands it to another subsystem, and watches it get unmarshaled.</p>
<ol><li><strong><code>encoding/json/v2</code> is the canonical JSON impl.</strong> When the</li></ol>
<p> binary is compiled with <code>GOEXPERIMENT=jsonv2</code>, every JSON path in <code>hanzoai/zip</code> (and therefore every Hanzo HTTP handler) routes through stdlib <code>encoding/json/v2</code>. Without the flag, zip falls back to <code>encoding/json</code> v1. No third-party JSON library (<code>goccy/go-json</code>, <code>sonic</code>, <code>jsoniter</code>, …) is permitted in the Hanzo Go stack. Stdlib only.</p>
<ol><li><strong>ZAP RPC is the wire format when subsystems are split-deployed.</strong></li></ol>
<p> The same <code>cloud.&lt;Subsystem&gt;Client</code> 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.</p>
<ol><li><strong>One JSON entry point per Hanzo Go binary.</strong> <code>hanzoai/zip</code></li></ol>
<p> internal/jsonenc package; selected at compile time by <code>goexperiment.jsonv2</code> build tag. <code>zip.JSONVariant</code> is a constant exposing which impl is active (<code>encoding/json/v2</code> or <code>encoding/json</code>). <code>zip.New</code> logs it at startup so operators can confirm the impl from production logs.</p>
<ol><li><strong>Brand-neutral.</strong> All hostnames, brands, and domain references</li></ol>
<p> are config-driven per the existing brand-package contract — no <code>hanzo.ai</code> hardcodes in the wire-stack logic. The same binary serves <code>api.hanzo.ai</code>, <code>api.osage.cloud</code>, <code>api.lux.cloud</code>, etc.</p>
<h4>Inter-subsystem client wiring (cloud.Deps)</h4>
<p>Per HIP-0106 &quot;Subsystem-to-subsystem calls&quot;, <code>cloud.Deps</code> exposes typed clients (one per subsystem). <code>cloud.BuildDeps(cfg)</code> picks the implementation per subsystem:</p>
<p>| Subsystem state | Endpoint configured? | Resolves to | |---|---|---| | Enabled in this process | n/a | <code>nil</code> — the subsystem&#x27;s own <code>Mount()</code> installs its in-process Client | | Disabled | Yes (<code>CLOUD_&lt;NAME&gt;_ZAP_ADDR</code>) | ZAP RPC client targeting the endpoint | | Disabled | No | <code>clients.Disabled&lt;Name&gt;()</code> — fail-closed stub returning a clear error | | Payments / Vault | (always RPC per HIP-0106 solo-vault CDE) | ZAP RPC client at <code>CLOUD_PAYMENTS_ZAP_ADDR</code> / <code>CLOUD_VAULT_ZAP_ADDR</code>, or fail-closed disabled stub if no endpoint |</p>
<p>Subsystem code calls <code>deps.&lt;Name&gt;.&lt;Method&gt;(...)</code> without knowing the mode. The interface is the contract. Detection of the fail-closed stub at mount-time uses <code>clients.IsDisabled(err)</code>.</p>
<p>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 <code>zapc generate &lt;schema&gt;.zap --lang go --out ./zap/gen/</code> produces typed bindings, the placeholder types in <code>cloud/types/</code> become aliases to the generated structs.</p>
<h3>Canonical Hanzo Go stack</h3>
<p>The unified binary is opinionated. Every subsystem uses the same Go substrate. <strong>One way to do everything.</strong> No parallel frameworks, no parallel ORMs, no parallel loggers, no parallel wire formats.</p>
<p>| Concern | Canonical | Notes | |---|---|---| | Web framework | <code>hanzoai/zip</code> | The ONE Go web framework. Built on Fiber v3 / fasthttp (implementation detail). Sinatra/Express-style primary API. <strong>No <code>.Fast</code> escape hatch — zip is fast.</strong> | | ORM | <code>hanzoai/orm</code> | Backends: SQLite (today), SQL/MySQL/MSSQL/Oracle via <code>dbx</code> (wiring pending), ZapDB via <code>luxfi/database</code>, CR-SQLite for client-side distributed (license-permitting). | | Logger | <code>luxfi/log</code> | NEVER <code>uber-go/zap</code>, NEVER <code>log/slog</code>, NEVER stdlib <code>log</code>. | | Wire protocol | ZAP | Every subsystem ships <code>&lt;svc&gt;/schema/&lt;name&gt;.zap</code>. <code>zapc</code> generates Go/TS/Py/Rust bindings. No <code>.capnp</code> files in Hanzo-authored source. | | Storage durability | <code>hanzoai/replicate</code> over <code>hanzo/vfs</code> | Per HIP-0107 (streaming replication over vfs). Covers SQLite WAL, ZapDB log, blockchain state, generic logs through one pipeline. | | Object store interface | <code>hanzo/vfs</code> | The ONLY object-store interface. All sink-side bytes route through vfs. | | Analytical store | <code>hanzoai/datastore-go</code> | Separate from <code>orm</code>. NOT an ORM backend — different workload class. |</p>
<p><strong>Migration adapters (transitional only, not parallel ways to build new services):</strong> <code>zip.AdaptNetHTTP(http.Handler)</code>, <code>zip.AdaptNetHTTPFunc(http.HandlerFunc)</code>, <code>zip.AdaptNetHTTPMiddleware(func(http.Handler) http.Handler)</code>, and <code>app.Mount(prefix, http.Handler)</code> as the path-prefixed mount form. <code>chi.Router</code>, <code>gin.Engine</code>, and <code>beego.App.Handlers</code> all satisfy <code>http.Handler</code> 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. <strong>New code must be written natively against zip.</strong> Adapters cost ~5% per-request perf versus native Fiber dispatch and that cost compounds at high RPS; replace adapted routes when feasible.</p>
<p>The framework itself is <strong><code>hanzoai/zip</code> v0.1.0+</strong> on <code>feat/fiber-v3</code> (commit train rebuilds upstream zeekay/zip from scratch on Fiber v3; see <code>hanzoai/zip</code> PR #1). zip is the ONE web framework. chi / gin / beego / echo are MIGRATION-ONLY and never appear in new Hanzo Go code.</p>
<h3>Process model</h3>
<p><code>cloud</code> is a single process exposing:</p>
<ul><li>One HTTP listener (default <code>:8080</code>) that fans out to subsystem</li></ul>
<p> handlers by URL prefix (<code>/v1/iam/...</code>, <code>/v1/base/...</code>, etc.)</p>
<ul><li>One ZAP RPC listener (default <code>:9653</code>) for service-to-service auth</li></ul>
<p> and inter-subsystem calls when split across binaries</p>
<ul><li>One health/metrics endpoint at <code>:9090</code></li><li>One admin endpoint at <code>:8081</code> (gated by IAM admin role)</li></ul>
<p>Subsystem activation:</p>
<pre><code class="lang-bash">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</code></pre>
<p>Each subsystem flag enables that subsystem&#x27;s HTTP routes, ZAP services, and background workers. Disabled subsystems contribute zero runtime cost beyond the compiled code in the binary.</p>
<h3>Subsystem boundaries</h3>
<p>Each Hanzo Go service exposes a single <code>Mount(app *zip.App, deps cloud.Deps) error</code> function (canonical signature; the old <code>chi.Router</code>-based shape is migrated through the <code>zip.AdaptChi</code> adapter). <code>cloud</code>&#x27;s <code>main.go</code> is essentially:</p>
<pre><code class="lang-go">import (
&quot;github.com/hanzoai/zip&quot;
&quot;github.com/hanzoai/iam&quot;
&quot;github.com/hanzoai/base&quot;
&quot;github.com/hanzoai/kms&quot;
&quot;github.com/hanzoai/commerce&quot;
&quot;github.com/hanzoai/ai&quot; // LLM control plane subsystem (was hanzoai/cloud pre-rename)
&quot;github.com/hanzoai/gateway&quot;
&quot;github.com/hanzoai/o11y&quot;
&quot;github.com/hanzoai/vfs&quot;
&quot;github.com/hanzoai/mq&quot;
&quot;github.com/hanzoai/dns&quot;
&quot;github.com/hanzoai/amqp&quot;
&quot;github.com/hanzoai/mcp&quot;
&quot;github.com/hanzoai/cloud&quot;
)
func main() {
cfg := cloud.LoadConfig()
deps := cloud.BuildDeps(cfg)
app := zip.New()
if cfg.Enabled(&quot;iam&quot;) { iam.Mount(app, deps) }
if cfg.Enabled(&quot;kms&quot;) { kms.Mount(app, deps) }
if cfg.Enabled(&quot;base&quot;) { base.Mount(app, deps) }
if cfg.Enabled(&quot;commerce&quot;) { commerce.Mount(app, deps) }
if cfg.Enabled(&quot;ai&quot;) { ai.Mount(app, deps) }
if cfg.Enabled(&quot;gateway&quot;) { gateway.Mount(app, deps) }
if cfg.Enabled(&quot;o11y&quot;) { o11y.Mount(app, deps) }
if cfg.Enabled(&quot;vfs&quot;) { vfs.Mount(app, deps) }
if cfg.Enabled(&quot;mq&quot;) { mq.Mount(app, deps) }
if cfg.Enabled(&quot;dns&quot;) { dns.Mount(app, deps) }
if cfg.Enabled(&quot;amqp&quot;) { amqp.Mount(app, deps) }
if cfg.Enabled(&quot;mcp&quot;) { mcp.Mount(app, deps) }
// ...
cloud.Serve(app, cfg) // HTTP + ZAP RPC + admin
}</code></pre>
<p>This means <strong>every existing Go service must expose a <code>Mount</code> function</strong> in addition to its <code>cmd/&lt;service&gt;/main.go</code>. The <code>main.go</code> becomes a thin shim that calls <code>Mount</code> on its own; <code>cloud</code>&#x27;s main calls the same <code>Mount</code> from its own binary. No business logic moves.</p>
<blockquote><p><strong>Realized refinement:</strong> the explicit <code>if cfg.Enabled(...)</code> enumeration above shipped as the registry pattern — <code>cloud.Register(name, order, mount)</code> from each subsystem&#x27;s <code>init()</code> plus a blank import in <code>cmd/cloud</code>, with <code>MountAll</code>/<code>ShutdownAll</code> driving ordered mount and reverse-ordered teardown. See &quot;Realized state&quot; above. The <code>Mount</code> contract itself is unchanged.</p></blockquote>
<p>Reference implementations already in tree (per <code>AUDIT_2026_05_19.md</code>): <strong><code>commerce</code>, <code>gateway</code>, <code>vfs</code></strong> — these export <code>Mount(...)</code> today. New subsystems join by mirroring their shape.</p>
<h3>ZAP schema contract</h3>
<p>Every subsystem ships a public <code>.zap</code> schema describing its in-process and over-wire interface. Build pipeline:</p>
<pre><code>&lt;subsystem&gt;/
schema/&lt;name&gt;.zap # public typed interface
zap/gen/ # zapc-generated bindings (Go for our use, others optional)
&lt;name&gt;.go # generated structs + interfaces
&lt;name&gt;_server.go # server-side handlers
&lt;name&gt;_client.go # typed client (in-process or RPC)
Makefile / build.sh # `zapc generate &lt;schema&gt;.zap --lang go --out ./zap/gen/`</code></pre>
<p><code>zapc</code> is the Rust-implemented Hanzo ZAP compiler at <code>~/work/hanzo/zap/zapc-rs/</code>. Multi-language codegen: <code>zapc generate file.zap --lang {go,ts,py,rust}</code>.</p>
<p>When <code>cloud</code> runs subsystems in-process: each <code>Mount(...)</code> registers its <code>*_server.go</code> against the local ZAP dispatcher, and the typed client interfaces in <code>deps</code> resolve to <strong>direct Go function calls through the ZAP runtime</strong> (no marshalling, no network). When subsystems are split: same generated client makes ZAP RPC calls over the wire. Same business code in either mode.</p>
<p><strong>Existing <code>.zap</code> schemas in production</strong> (real, not aspirational):</p>
<ul><li><code>~/work/hanzo/ai/ai.zap</code> (was <code>~/work/hanzo/cloud/cloud.zap</code> pre-rename) — LLM control plane types (ChatMessage, ModelProvider, ChatCompletion)</li><li><code>~/work/hanzo/commerce/api/billing/billing.zap</code> — billing schemas</li><li><code>~/work/hanzo/tasks/schema/tasks.zap</code> — task scheduling</li><li><code>~/work/hanzo/zap/rust/schema/zap.zap</code> — self-describing schema</li></ul>
<p>Subsystems with generated bindings under <code>&lt;svc&gt;/zap/</code>: <code>python-sdk/proto/zap</code>, <code>kv/modules/zap</code>, <code>playground/internal/zap</code>, <code>hanzo.ai/components/zap</code>, <code>platform/pkg/zap</code>, <code>mcp/dist/zap</code>, <code>dev/hanzo-dev/zap</code>, <code>docdb/internal/zap</code>, <code>vector/src/zap</code>. At least 10+ subsystems already on the pattern.</p>
<p><strong>Policy</strong>: no <code>.capnp</code> files. No &quot;Cap&#x27;n Proto&quot; 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.)</p>
<h3>Edge + stateless scaling</h3>
<p>The <code>cloud</code> 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&#x27;s SQLite file from local storage (cached) or the encrypted S3 mirror (cold).</p>
<pre><code>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. │
└──────────────────────────────────────┘</code></pre>
<h4>Routing</h4>
<p>The load balancer routes external requests to any replica. Consistent-hash on <code>X-Org-Id</code> (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.</p>
<h4>Gateway as edge subsystem</h4>
<p>Within each replica, the <code>gateway</code> subsystem owns the edge concerns:</p>
<ul><li>JWT validation against <code>iam</code> JWKS</li><li>Identity-header strip + gateway-minted <code>X-Org-Id</code> per <code>iam.tenantClaim</code></li><li>Per-route policy + rate limiting</li></ul>
<p>After gateway, calls between subsystems use ZAP-typed Go method calls (see &quot;Subsystem boundaries&quot;); no per-hop JSON marshalling. JSON marshal runs at most once per request, at the subsystem handler boundary, returning to the gateway response path.</p>
<h4>Scaling characteristics</h4>
<p>| 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 |</p>
<p>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&#x27;s per-replica throughput.</p>
<p>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 <code>Mount()</code> until first request.</p>
<h4>Per-replica capacity budget</h4>
<p>The verified, measured budget for a Hanzo <code>zip</code>-on-<code>fasthttp</code> replica (Apple M1 Max / Go 1.26.3 / Fiber v3 v3.2.0, gateway hot-path):</p>
<p>| Conns | Heap delta | Per-conn heap | Goroutines | |---|---:|---:|---:| | 1,000 | 7.84 MiB | <strong>8.02 KiB</strong> | <strong>1.00 / conn</strong> | | 8,454 | 67 MiB | <strong>8.02 KiB</strong> | <strong>1.00 / conn</strong> |</p>
<p>| 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 |</p>
<p>The operational target is <strong>100k concurrent client connections per replica</strong> 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 <code>zip.Config.Concurrency: 100_000</code> to stay inside the budget; the kernel ulimit must be configured accordingly via the pod&#x27;s securityContext.</p>
<p>JSON impl at the edge: every production <code>cloud</code> Dockerfile compiles with <code>GOEXPERIMENT=jsonv2</code>. Verified edge-path wins on Apple M1 Max / Go 1.26 / zip on Fiber v3 v3.2.0:</p>
<p>| Bench | json/v1 | json/v2 | Δ | |---|---|---|---| | Edge POST roundtrip | 19,782 ns / 73 allocs | 17,406 ns / 56 allocs | <strong>−12% time, −23% allocs</strong> | | Marshal-only | 12,860 ns / 34 allocs | 10,092 ns / 34 allocs | <strong>−22% time</strong> | | Unmarshal-only | 17,122 ns / 67 allocs | 13,785 ns / 50 allocs | <strong>−19% time, −25% allocs</strong> |</p>
<p>JSON marshal runs <strong>at most once per request</strong> (at the gateway edge); inter-subsystem calls use ZAP. The −22% marshal-only win lands once, on the response path to the client.</p>
<p>Reproduce:</p>
<pre><code class="lang-bash">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</code></pre>
<p>Canonical scale doc: <code>~/work/hanzo/hips/docs/SCALE_STANDARD.md</code>.</p>
<h4>Single-process invariant</h4>
<p>By design, the <code>cloud</code> binary holds no per-tenant state in process memory beyond:</p>
<ul><li>the read-side page cache for SQLite (evictable, <code>pragma cache_size</code>-bounded)</li><li>the wazero/goja/pyvm extension runtime pools (HIP-0105, HIP-0108)</li><li>the in-process Deps-client method dispatch table</li></ul>
<p>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.</p>
<h4>Anti-patterns</h4>
<ul><li>Replica-local caches keyed by tenant ID without time-based eviction</li></ul>
<p> → causes memory leak under tenant churn</p>
<ul><li>Cross-replica in-memory pub-sub (sharing state via NATS in-memory</li></ul>
<p> topics) → use durable queue subsystem (<code>mq</code>, <code>amqp</code>) instead</p>
<ul><li>Sticky-session affinity REQUIRED (vs. preferred) → forces stateful</li></ul>
<p> load balancer config; breaks the &quot;any replica serves any tenant&quot; invariant. The X-Org-Id consistent hash is an optimization, not a contract.</p>
<h3>Tenant isolation</h3>
<p>| Layer | Today | Under HIP-106 | |---|---|---| | <strong>Auth</strong> | Per-domain IAM (multi-tenant) | Unchanged. IAM resolves <code>(app, org)</code> from origin; subsystems see JWT claims via <code>X-Org-Id</code>. | | <strong>Storage</strong> | Per-service postgres or per-tenant SQLite (varies) | Always per-tenant SQLite (<code>{data-dir}/orgs/{org}/{service}.db</code>) with per-org DEK per HIP-0302. No postgres in the unified path. | | <strong>KMS</strong> | Per-org master keys today | Unchanged. KMS in-process serves <code>kms://&lt;deployment&gt;/&lt;org&gt;/&lt;purpose&gt;</code> references. | | <strong>Cache</strong> | Per-service KV (varies) | Process-local LRU or per-org sub-buckets in shared in-memory cache. No KV. | | <strong>Brand</strong> | Per-domain detection in app code | <code>cfg.Brand</code> at startup; subsystems read brand from deps; UI templates resolved from embedded assets. |</p>
<h3>Subsystem-to-subsystem calls</h3>
<p>In the unified binary, IAM, KMS, Base, Commerce, Cloud, etc. live in the <strong>same process address space</strong>. Inter-subsystem calls are <strong>ZAP-typed Go function calls</strong> via the deps:</p>
<pre><code class="lang-go">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
}</code></pre>
<p>Each generated <code>Client</code> has two implementations:</p>
<ul><li><strong>in-process</strong> (direct method calls through the local ZAP dispatcher)</li><li><strong>RPC</strong> (ZAP-typed RPC over the wire)</li></ul>
<p><code>cloud</code> wires in-process. Legacy split deploys wire RPC. Same business code in either mode. <strong>Every subsystem boundary is typed end to end</strong> via the <code>.zap</code> schema.</p>
<h3>Extension surface</h3>
<p>User-supplied code inside the unified binary uses the in-process extension runtime from HIP-0105:</p>
<ul><li>Per-record hooks in Base → <strong>goja</strong> (per HIP-0105 scale findings:</li></ul>
<p> goja wins multi-tenant SaaS at scale)</p>
<ul><li>Per-request policy rules in Gateway → <strong>wazero</strong> (untrusted) or</li></ul>
<p> <strong>native</strong> (Hanzo-authored)</p>
<ul><li>Custom prompt transforms for AI (LLM control plane subsystem) → <strong>wazero</strong></li><li>Custom tool functions for Agents → <strong>wazero</strong></li></ul>
<p>The extension runtime IS the user-code boundary inside the unified process. Don&#x27;t shell out, don&#x27;t spawn sidecars, don&#x27;t run Knative pods for per-request hooks. HIP-0060 (Functions) handles the workloads where those overheads are justified.</p>
<h3>Multi-language handlers</h3>
<p>HIP-0105 defines two mount points (in-process Base hooks AND web routes via <code>hanzoai/zip</code>). The unified binary uses <strong>mount point #2</strong> to allow service routes themselves to be authored in any HIP-0105-supported language:</p>
<p>| Language | Runtime name | Mount path | |---|---|---| | Go (Hanzo-authored) | native | direct in-process — default for all service code | | Rust / C++ / Zig / AssemblyScript | <code>wasm</code> (wazero) | compiled to <code>*.wasm</code>, loaded under <code>hz_routes/&lt;name&gt;/</code> | | JavaScript / TypeScript | <code>goja</code> (production) or <code>v8go</code> (experimental) | source files loaded directly | | Python | <code>pyvm</code> (single-tenant only, <code>-tags pyvm</code>) | CPython 3.13 sub-interpreter pool | | DSL / policy | <code>starlark</code> | sandboxed, deterministic, no I/O by default |</p>
<p><strong>Every HIP-0105 runtime is mountable as a route via the SAME entry point</strong>: <code>app.Module(method+path, runtimeName, modulePath)</code>. One method on the zip.App; one canonical JSON envelope shape (<code>{method, path, params, query, headers, body, org, user, userEmail}</code>) every guest sees; one response envelope (<code>{status, headers, body}</code>) every guest returns. There is no per-runtime mount API — <code>app.ModuleWasm</code> / <code>app.ModuleGoja</code> / <code>app.ModulePython</code> do not exist on purpose. One way.</p>
<pre><code class="lang-go">app.Module(&quot;POST /v1/policy/eval&quot;, &quot;wasm&quot;, &quot;./ext/policy&quot;) // Rust/AS/Zig/C → wasm via wazero
app.Module(&quot;POST /v1/transform&quot;, &quot;pyvm&quot;, &quot;./ext/transform&quot;) // single-tenant CPython
app.Module(&quot;POST /v1/webhook&quot;, &quot;goja&quot;, &quot;./ext/webhook&quot;) // recommended multi-tenant JS
app.Module(&quot;POST /v1/route&quot;, &quot;starlark&quot;, &quot;./ext/route&quot;) // config DSL</code></pre>
<p>The route author writes their handler in their preferred language; the same <code>.zap</code> 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 <strong>duck-typed</strong> via <code>zip/runtime.Loader</code> so zip itself stays decoupled from <code>hanzoai/base/plugins/extruntime</code> (the canonical loader implementation); the unified binary constructs <code>*extruntime.Loader</code> once with whichever runtimes it cares about and threads it into <code>zip.Config.Loader</code>.</p>
<p>Multi-tenant deployments MUST gate <code>AllowedRuntimes</code> on <code>zip.Config</code> to exclude runtimes lacking hard sandbox (pyvm, v8go). <code>AllowedRuntimes: nil</code> accepts whatever the Loader has registered.</p>
<h3>API keys</h3>
<p>The credential for programmatic access is an API key. IAM mints and verifies it, <code>gateway</code> 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:</p>
<p>| Type | Prefix | Where it belongs | |---|---|---| | publishable | <code>pk-</code> | browser and client code; identifies an org, authorizes nothing that spends | | secret | <code>sk-</code> | server side only; carries the caller&#x27;s full scope |</p>
<p><code>hk-</code> is the older name for a secret key. Verification still accepts one; nothing has minted one since <code>iam</code> v1.33.9.</p>
<pre><code>GET /v1/keys # the caller&#x27;s keys: { type, prefix, createdAt }
POST /v1/keys # mint or rotate the key of { type }
DELETE /v1/keys # revoke the key of that type</code></pre>
<p><strong>The secret is returned exactly once, at mint.</strong> 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.</p>
<p>A key carries a scope, and the scope is enforced at the gateway edge before any subsystem sees the request:</p>
<p>| Field | Meaning | |---|---| | <code>models</code> | which models the key may address; <code>*</code> for all | | <code>services</code> | which subsystems it may invoke — <code>llm</code>, <code>agents</code>, <code>mcp</code>, <code>embeddings</code>, <code>images</code>, <code>audio</code> | | <code>rateLimit</code> | requests per minute; default 60 | | <code>spendLimit</code> | ceiling in USD cents per billing period; unset means the org balance is the only ceiling | | <code>allowedIPs</code> | CIDR allowlist; unset means any address | | <code>expiresAt</code> | expiry; unset means the key lives until revoked |</p>
<h3>Credit metering</h3>
<p>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.</p>
<p><code>commerce</code> owns the balance. The metering client is the one place this binary asks about money, and it wraps every priced request in two calls:</p>
<ol><li><strong>Authorize</strong>, before the handler runs. Sufficient balance passes.</li></ol>
<p> Insufficient balance is <code>402 insufficient_balance</code> and the handler never runs. An unreachable <code>commerce</code> is <code>503 balance_unavailable</code>.</p>
<ol><li><strong>Record</strong>, after the handler returns, with the units the request</li></ol>
<p> actually consumed.</p>
<p><strong>Fail-closed is the default</strong>: when <code>commerce</code> 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.</p>
<p>A usage event says who spent, what served it, what it consumed and how it went. It carries no prompt content and no PII.</p>
<pre><code class="lang-go">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
}</code></pre>
<p>Events are written to the calling tenant&#x27;s own store, so a usage read is org-scoped by construction rather than by a <code>WHERE</code> clause, and <code>commerce</code> aggregates them for invoicing and reseller revenue share.</p>
<pre><code>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</code></pre>
<p>All six accept <code>start</code>, <code>end</code>, <code>granularity</code> and <code>filter</code>. 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.</p>
<h3>OpenAI-compatible surface</h3>
<p>The inference surface is OpenAI&#x27;s, so an existing application moves by changing two strings:</p>
<pre><code class="lang-python">from openai import OpenAI
client = OpenAI(
api_key=&quot;sk-...&quot;,
base_url=&quot;https://api.hanzo.ai/v1&quot;,
)
response = client.chat.completions.create(
model=&quot;zen-8b-instruct&quot;,
messages=[{&quot;role&quot;: &quot;user&quot;, &quot;content&quot;: &quot;Hello&quot;}],
)</code></pre>
<pre><code>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</code></pre>
<p>The <code>ai</code> subsystem holds the model catalog and the routing policy; <code>gateway</code> speaks the OpenAI shape at the edge and absorbs provider-specific differences. Both are subsystems of this binary, so a request arriving at <code>/v1/chat/completions</code> is authenticated, authorized against the balance, routed, served and recorded without leaving the process.</p>
<h3>Deployment surfaces this enables</h3>
<p>| 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 |</p>
<p>Same image. Different startup configuration. The <code>osage.cloud</code> marketing site that shipped 2026-05-19 gets a real backend when this HIP lands.</p>
<h2>Migration plan</h2>
<p>Multi-week real engineering. Order revised from <code>AUDIT_2026_05_19.md</code> findings:</p>
<h3>Phase 1 — Mount contract on reference + smallest services (1 week)</h3>
<p>Per <code>AUDIT_2026_05_19.md</code>, three subsystems <strong>already export <code>Mount(...)</code></strong>: <strong><code>commerce</code>, <code>gateway</code>, <code>vfs</code></strong>. These are the reference impls — Phase 1 first reshapes their signatures to the canonical <code>(*zip.App, Deps) error</code> form, then extends the same shape to the smallest remaining services:</p>
<p><strong>Reference impls (already Mount-shaped):</strong></p>
<ol><li><strong>commerce</strong> — production, multi-tenant (37 X-Org-Id call-sites),</li></ol>
<p> IAM-integrated, <code>Mount</code> exists. Reshape <code>Deps</code> to the canonical interface and use it as the live blueprint.</p>
<ol><li><strong>gateway</strong> — <code>Mount</code> exists. Validate that the subsystem can be</li></ol>
<p> both standalone and embedded.</p>
<ol><li><strong>vfs</strong> — <code>Mount</code> exists. Smallest of the three.</li></ol>
<p><strong>Smallest remaining services to bring to the Mount contract:</strong></p>
<ol><li><strong>kms</strong> — smallest service still needing <code>Mount</code>; clean deps.</li><li><strong>dns</strong> — small, no auth dep.</li><li><strong>amqp</strong> — small, no auth dep.</li><li><strong>authz</strong> — first to consume <code>deps.IAM</code>.</li></ol>
<p><strong>Explicitly excluded from Phase 1 (and from the unified binary entirely):</strong></p>
<ul><li><strong><code>vault</code></strong> — PCI-CDE. Folding it into a multi-tenant process</li></ul>
<p> expands PCI scope to every other tenant. Stays its own deployment. See Non-goals.</p>
<h3>Phase 2 — Ship <code>cloud</code> (1 week)</h3>
<p><code>~/work/hanzo/cloud/cmd/cloud/main.go</code> — new repo <code>github.com/hanzoai/cloud</code>. Imports the seven subsystems from Phase 1, wires Deps, dispatches by subsystem flag. Ship as <code>ghcr.io/hanzoai/cloud:v0.1.0</code>. Single-tenant smoke deployment at a dev domain first.</p>
<h3>Phase 3 — Fold the heavy subsystems (2 weeks)</h3>
<ol><li><strong>iam</strong> — has its own SPA; mount handlers without changing SPA</li><li><strong>base</strong> — <code>plugins/extruntime</code>, <code>plugins/jsvm</code>, <code>plugins/wasmvm</code></li></ol>
<p> must remain isolated per-org (per HIP-0105)</p>
<ol><li><strong>o11y</strong> — heaviest multi-tenant footprint (309 X-Org-Id call-sites</li></ol>
<p> per audit). Get this right and the per-tenant routing pattern is proven for everything else.</p>
<ol><li><strong>ai</strong> (LLM control plane) — mount existing routes</li><li><strong>mcp</strong> — depends on iam</li><li><strong>mq</strong> — depends on base for durability</li><li><strong>ingress</strong> — depends on gateway routes</li></ol>
<h3>Phase 4 — Tenant routing layer (1 week)</h3>
<p>Universal <code>X-Org-Id</code> 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.</p>
<h3>Phase 5 — Reseller provisioning + operator convergence (1 week)</h3>
<p>Operator CRD <code>ResellerCloud{name, parentOrg, brand, enabledSubsystems}</code> that creates the IAM app + KMS namespace + Base storage allocation + Gateway routes atomically. Documented at <code>~/work/hanzo/cloud/docs/RESELLER.md</code>. Self-serve resell becomes possible.</p>
<p><strong>Operator convergence (BLOCKER for Phase 5).</strong> The audit identified three parallel operator lineages:</p>
<ul><li><code>~/work/hanzo/operator</code> (Go)</li><li><code>~/work/hanzo/hanzo-operator</code> (Go, production)</li><li><code>~/work/hanzo/operator-core</code> (Rust)</li></ul>
<p>Phase 5 cannot ship until one is picked and the other two are either folded in or archived. Recommended path: keep <code>hanzo-operator</code> (the production lineage with the existing ClusterRole), fold the <code>ResellerCloud</code> CRD into it, archive <code>operator/</code>, and demote <code>operator-core</code> to a Rust library (<code>library-no-action</code> per audit) for shared CRD types. Decision required before Phase 5 starts.</p>
<h3>Phase 6 — Billing wiring (separate HIP follow-up)</h3>
<p>Commerce subsystem reads per-tenant usage from base + o11y/Datastore and applies the reseller revenue-share contract. <strong><code>commerce</code> is the canonical billing/pricing/subscription home</strong> — the TS <code>billing</code> and <code>pricing</code> packages get absorbed into <code>commerce</code> via Go rewrites.</p>
<p><strong>Note on <code>auto</code></strong>: the earlier audit grouped <code>auto</code> with billing/pricing for commerce absorption. <strong>This was wrong.</strong> <code>~/work/hanzo/auto</code> is a plug-n-play IFTT-style trigger framework that sits on top of <code>~/work/hanzo/tasks</code> (durable task queue). It is <strong>NOT</strong> under commerce. <code>auto</code> is its own subsystem and mounts independently. <code>tasks</code> is its own subsystem — the durable-queue primitive used by <code>auto</code>, by <code>commerce</code> recurring billing, by <code>o11y</code> retention jobs, and by anything else that needs durable scheduling.</p>
<h2>Commerce — light router, NOT in PCI-DSS scope</h2>
<p><strong>Commerce is a thin orchestrator.</strong> It owns the customer-facing checkout flow, tenant config, billing logic, pricing logic, invoicing, and webhook intake. It explicitly does NOT:</p>
<ul><li>Touch a Primary Account Number (PAN)</li><li>Process card data</li><li>Implement processor connector logic (native PSP SDK /</li></ul>
<p> Adyen SDK)</p>
<ul><li>Store encrypted PAN</li></ul>
<p>Commerce only handles <strong>tokens</strong> (vault tokens) and <strong>intents</strong> (payments-orchestrator references). When commerce needs to charge, it calls <code>payments</code> (Rust) via ZAP RPC with a token + amount + processor hint. Payments calls <code>vault</code> (Go) via ZAP RPC with a &quot;Charge this token&quot; request; vault pulls the PAN from its encrypted store, makes the outbound HTTPS to the processor, and returns the response. <strong>PAN never leaves vault.</strong></p>
<p>This makes commerce <strong>CDE-connected</strong>, not <strong>CDE</strong>. Lighter controls apply (network segmentation, access control, change management) but commerce is NOT subject to PCI-DSS L1 audit.</p>
<h2>Solo-vault CDE</h2>
<p><strong>Vault is the only system in PCI-CDE.</strong> Per the corrected scope:</p>
<p>| System | PCI scope | |---|---| | <code>vault</code> | <strong>CDE</strong> — the only system that touches PAN. Full L1 audit. Quarterly ASV. HSM-backed key store. Own deployment, own k8s namespace, own NetworkPolicy boundary. | | <code>payments</code> | <strong>CDE-connected</strong> (NOT CDE). Sees only tokens. Payments service operated in tokens-only mode. Calls <code>vault.Charge(token, processor, amount)</code> for the actual processor call. | | <code>commerce</code> | <strong>CDE-connected</strong> (NOT CDE). Light router. Only ever handles tokens + intent IDs. Mounts inside cloud like any other subsystem. | | Everything else in cloud | <strong>Not CDE-connected.</strong> Standard SOC2-grade controls. |</p>
<p>For this architecture to be sound, two requirements must hold:</p>
<ol><li><strong>Browser-side card collection runs directly against vault</strong> (vault</li></ol>
<p> ships a <code>vault-collect.js</code> iframe; PAN posts directly to vault from the browser, never via commerce or any Hanzo app server).</p>
<ol><li><strong>Payments runs in tokens-only mode</strong> — verified by</li></ol>
<p> audit of payments data flow that no code path exposes raw PAN to the surrounding Go process.</p>
<p>Both are tracked under the implementation TODO list at <code>~/work/hanzo/vault/docs/</code> (to be created).</p>
<h2>PSP optionality</h2>
<p>The same architecture supports four deployment modes:</p>
<ol><li><strong>Default (Hanzo as merchant)</strong>: Hanzo operates vault + payments +</li></ol>
<p> commerce. Hanzo bears the PCI-DSS L1 audit. PCI scope = vault only.</p>
<ol><li><strong>Hanzo as PSP for a white-label customer</strong>: customer&#x27;s brand</li></ol>
<p> (<code>lux.cloud</code>, <code>zoo.cloud</code>, <code>osage.cloud</code>) runs commerce inside their cloud deployment; commerce&#x27;s <code>payments_client</code> and <code>vault_client</code> ZAP endpoints point at Hanzo&#x27;s payments + vault. Customer carries no PCI obligation. Hanzo&#x27;s vault has multi-tenant token namespacing per org.</p>
<ol><li><strong>Customer brings their own PSP backend</strong>: customer deploys their own</li></ol>
<p> vault + payments. Their cloud&#x27;s commerce subsystem points its ZAP-RPC endpoints at THEIR vault + payments deployment. <strong>Hanzo carries no PCI obligation for that customer&#x27;s flows.</strong> The customer holds their own PCI scope. Commerce is a swappable thin router.</p>
<ol><li><strong>Single-tenant Hanzo Payments-as-a-product</strong>: customer&#x27;s ENTIRE</li></ol>
<p> 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.</p>
<p>Modes 1-3 share the same binary. Configuration determines which endpoints commerce talks to. The &quot;swappable thin router&quot; property is load-bearing: commerce never grows code that depends on a specific vault or payments operator.</p>
<h2>Non-goals</h2>
<ul><li><strong>TS service rewrite as part of this HIP.</strong> Platform (Next.js /</li></ul>
<p> 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.</p>
<ul><li><strong><code>vault</code> and <code>payments</code> are explicitly NOT folded.</strong> Both stay as</li></ul>
<p> their own deployments with their own PCI scope boundaries per the &quot;Solo-vault CDE&quot; section above. Vault is CDE. Payments is CDE-connected. Commerce talks to both via ZAP RPC. <strong>Hard rule, no exceptions</strong> — even single-tenant deployments use the three-process architecture.</p>
<ul><li><strong><code>~/work/hanzo/flow</code> (Hanzo Flow — visual ML pipeline / agent-building) is NOT folded.</strong> Visual ML</li></ul>
<p> 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 (&gt;=2.6).</p>
<ul><li><strong><code>~/work/hanzo/datastore</code> (Datastore fork) is NOT folded.</strong> OLAP</li></ul>
<p> column store. Uses Datastore-native ReplicatedMergeTree + S3 disk. Out of scope. Shares S3 bucket with HIP-0107 streaming via vfs prefix (<code>s3://bucket/datastore/...</code> vs <code>s3://bucket/replicate/...</code>).</p>
<ul><li>**<code>~/work/hanzo/insights</code> (Hanzo Insights — AI observability + eval + prompt management) is NOT</li></ul>
<p> 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 <code>cloud</code> subsystem (LLM control plane) and surfaced to operators as part of the AI console.</p>
<ul><li>**Other Python services flagged RED by the 2026-05-19 free-threading</li></ul>
<p> audit** (<code>cli</code>, <code>erp</code>, <code>insights</code>, <code>sentry</code>, <code>studio</code>) — all stay separate processes until their upstream FT-blockers clear (xmlsec, confluent-kafka, chdb, single-threaded Django/Celery assumptions, torch &lt;2.6). Run under regular <code>python3.13</code> (GIL-enabled) until then.</p>
<ul><li><strong>Cross-deployment service mesh.</strong> The unified binary collapses</li></ul>
<p> in-deployment service calls; cross-deployment (Hanzo ↔ Lux ↔ Zoo) stays on the existing service-discovery + bridge layer.</p>
<ul><li><strong>Auto-scaling per-subsystem.</strong> All subsystems in one binary scale</li></ul>
<p> 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.</p>
<h2>Open questions</h2>
<ol><li><strong>Cold start under load</strong> — single binary with all subsystems boots</li></ol>
<p> slower than a focused service. Acceptable for long-lived deployments; needs measurement for fast-restart scenarios. Suggest benchmarking on Phase 2.</p>
<ol><li><strong>Per-subsystem memory budgets</strong> — one OOM kills every subsystem.</li></ol>
<p> Acceptable trade-off for resell where blast radius is per-customer anyway, but Hanzo flagship may want to keep some subsystems split.</p>
<ol><li><strong>Routes that conflict</strong> — <code>/v1/iam/...</code>, <code>/v1/base/...</code>,</li></ol>
<p> <code>/v1/commerce/...</code>, etc. Already mostly per-subsystem-prefixed. The unified mux compiles a route table at startup and refuses to start on collision.</p>
<ol><li><strong>Build-time flags vs runtime flags</strong> — for production we want</li></ol>
<p> every subsystem compiled in. For developer builds we might want to disable some at build time to shrink the binary. <strong>ANSWERED by HIP-0116</strong>: neither build tags nor bigger binaries — services build standalone AND as ZAP-native plugin VMs (<code>luxfi/lpm</code>-installed, dispatched over ZAP per HIP-0114). Build tags are explicitly rejected there; runtime enablement stays the CLI/env flags specified here.</p>
<ol><li><strong>ZAP versioning</strong> — when a subsystem evolves its <code>.zap</code> schema,</li></ol>
<p> how do we manage cross-version compat? Suggest semver on the <code>.zap</code> file itself (<code>@version 1.2.0</code> directive) and <code>zapc</code> refusing breaking changes without an explicit major bump. Tracked for follow-up.</p>
<ol><li><strong>Three competing operator lineages</strong> — <code>operator/</code>,</li></ol>
<p> <code>hanzo-operator/</code>, <code>operator-core/</code> (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.</p>
<h2>References</h2>
<ul><li>Reference: Discord (single binary serving all microservices),</li></ul>
<p> Tailscale (one tailscaled), GitLab (omnibus)</p>
<ul><li><code>~/work/hanzo/AUDIT_2026_05_19.md</code> — ecosystem audit driving the</li></ul>
<p> migration order</p>
<ul><li>HIP-0014 — Application Deployment Standard (per-service binaries</li></ul>
<p> today)</p>
<ul><li>HIP-0026 — IAM (unified auth across the deployment)</li><li>HIP-0027 — KMS (unified secrets store)</li><li>HIP-0105 — In-Process Extension Runtime (the user-code substrate</li></ul>
<p> inside the unified binary)</p>
<ul><li>HIP-0010 — Model Context Protocol Integration Standards (the MCP subsystem inside</li></ul>
<p> the binary)</p>
<ul><li>HIP-0301 — Agent Runtime Protocols &amp; Cross-Platform Parity (agents</li></ul>
<p> subsystem must satisfy)</p>
<ul><li>HIP-0302 — Hanzo Replicate: Encrypted SQLite + ZapDB Durability for</li></ul>
<p> Base Services (the per-tenant data isolation model — covers both Base&#x27;s SQLite backend AND ZapDB-backed deployments)</p>
<ul><li>HIP-0107 — Streaming Replication over VFS (the unified streaming</li></ul>
<p> pipeline; supersedes the per-backend sink code in HIP-0302&#x27;s reference impl — substrate stays, transport unifies)</p>
<ul><li>HIP-0029 — Relational Database Standard (SQLite-primary per-tenant</li></ul>
<p> storage — the realized default)</p>
<ul><li>HIP-0018 / HIP-0422 — payment processing / billing (the metering +</li></ul>
<p> balance-floor semantics gated at this binary&#x27;s edge)</p>
<ul><li>HIP-0114 — ZAP — Inter-VM Cognitive Transport (envelope, framing,</li></ul>
<p> authentication for the ZAP contract this HIP mandates)</p>
<ul><li>HIP-0116 — Hanzo Plugin &amp; VM Model (how subsystems take shape:</li></ul>
<p> standalone / embedded / plugin VM; answers Open Question 4)</p>
<ul><li>HIP-0117 — Cloud-in-a-Box — One Binary, Three Modes (deployment</li></ul>
<p> topologies of this binary)</p>
<footer>
<div class="fmap">
<div><b>Build</b>
<a href="https://hanzo.app">hanzo.app</a> app builder
<a href="https://hanzo.codes">hanzo.codes</a> code with an agent
<a href="https://hanzoskills.com">hanzoskills.com</a> what an agent reads</div>
<div><b>Run</b>
<a href="https://console.hanzo.ai">console.hanzo.ai</a> cloud console
<a href="https://api.hanzo.ai">api.hanzo.ai</a> the API</div>
<div><b>Account</b>
<a href="https://hanzo.id">hanzo.id</a> sign in
<a href="https://pay.hanzo.ai">pay.hanzo.ai</a> top up
<a href="https://billing.hanzo.ai">billing.hanzo.ai</a> invoices and usage</div>
<div><b>Company</b>
<a href="https://hanzo.ai">hanzo.ai</a> canonical
<a href="https://hanzo.ventures">hanzo.ventures</a> ventures</div>
</div>
<div class="fend"><a href="/hip-0138.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
</footer>
</div>
</body></html>