mirror of
https://github.com/hanzoai/skills.git
synced 2026-11-19 00:47:36 +00:00
297 lines
29 KiB
HTML
297 lines
29 KiB
HTML
<!doctype html>
|
|
<html lang="en"><head>
|
|
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
|
|
<title>hip-0127</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-0127.md">
|
|
|
|
<link rel="icon" href="/favicon.svg">
|
|
<link rel="canonical" href="https://hanzoskills.com/hip-0127">
|
|
</head>
|
|
<!-- Reading this with a machine? Every page here is also plain markdown.
|
|
This one: https://hanzoskills.com/hip-0127.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-0127</h1><p class="lede">HIP-127: V8 · Open Edition — Architecture, Distribution & the Language Seam. Status Final. Hanzo architectural specification.</p><h1>HIP-0127: V8 · Open Edition — Architecture, Distribution & the Language Seam</h1>
|
|
<h2>Abstract</h2>
|
|
<p>The spine of Hanzo <strong>V8 · Open Edition</strong>: how the whole cloud is composed, split across languages, and distributed — as one coherent set of decisions so no consumer ever needs to know or care which part is Go and which is Rust. It ties together the plugin contract (HIP-0106), the ZAP transport (HIP-0114/0120), the CLI (HIP-0041), and the multi-language SDKs (HIP-0040) under one rule: <strong>one contract, many bindings, thin clients, and a wire — never FFI — between languages.</strong></p>
|
|
<h2>Motivation</h2>
|
|
<p>Hanzo is Go <em>and</em> Rust: the cloud is Go, the engine, the <code>dev</code> agent, and the ML kernels are Rust. The naive urges are both wrong:</p>
|
|
<ul><li>fuse them in one process over FFI (cgo/uniffi), or</li><li>split the GitHub orgs by language (<code>hanzo-go</code>/<code>hanzo-rs</code>).</li></ul>
|
|
<p>The first <em>complects</em> two toolchains: a Go⟷Rust FFI link means one build that needs both, a cross-compile matrix that is the product of the two, and a crash in either half landing in the other's process. The second leaks the implementation detail into the org, forcing users to know which half a capability lives in. V8 rejects both.</p>
|
|
<p>Note what this rejects and what it does not. It rejects a <strong>language seam</strong> over FFI; it is not a blanket ban on cgo. <code>make</code> defaults to <code>CGO_ENABLED=0</code> — a pure-Go build that registers exactly one <code>sqlite</code> driver — while the shipped image builds <code>CGO_ENABLED=1 -tags "libsqlite3 sqlite_fts5"</code> so stores link the live libsqlcipher codec (<code>cloud/Makefile</code>, which states outright that the shipped binary is not pure Go). One C library inside one Go binary is a dependency choice. Linking Rust into that same binary would be an architecture, and that is the thing refused here.</p>
|
|
<h2>Specification</h2>
|
|
<h3>1 — One contract, one host, many plugin binaries</h3>
|
|
<p>The application cloud is a <strong>light Go host</strong> (<code>cloud</code>) plus <strong>123 plugin binaries</strong>, composed at run time and not linked at build time (HIP-0106). The host holds no subsystem code. <code>manifest.Apps</code> — a hand-authored <code>var Apps = []App{…}</code> in <code>cloud</code>'s <code>manifest/apps.go</code> — is the source of truth for the set; <code>cmd/cloud/main.go</code> walks it and calls <code>zip.Load(p, a.Prefixes…)</code> per row, then <code>app.Use(leaf)</code>. Of the 123 rows, 4 are eager, 1 is co-resident (middleware on another app's router, mounting nothing of its own) and the rest load on first request. <strong>There is no <code>subsystems.go</code> in this path.</strong> Earlier drafts of this HIP named one; the only file by that name in <code>cloud</code> is <code>apps/admin/subsystems.go</code>, which <em>reports</em> on the composition and does not create it.</p>
|
|
<p>Its public surface is <strong><code>/v1/<capability></code></strong> over <strong>HTTP + ZAP</strong>, the ONE contract every consumer speaks. One capability = one name = one <code>/v1/<name></code> = one self-contained spec.</p>
|
|
<h4>1.1 — Three numbers, three questions, never conflated</h4>
|
|
<p>Every number below has one authority and answers one question. They are close in size and were repeatedly quoted for each other; that is the defect this subsection exists to end.</p>
|
|
<p>| Number | Question it answers | Authority | |---|---|---| | <strong>120 capabilities</strong> | Which names exist for a reader shown the whole API at once, and which of nine domains each sits under | <code>capabilities.yaml</code> in the <strong><code>hanzoai/openapi</code> repository</strong> — <code>openapi/</code> is the REPO name, not a directory inside <code>cloud</code> | | <strong>122 products</strong> | Which capability names the served document actually carries today | the operation <code>tags:</code> of <code>cloud</code>'s emitted <code>openapi.yaml</code> (2,335 operations across the 129 subsets) | | <strong>129 apps</strong> | How many things get built, shipped and started — the deployment unit | <code>manifest.Apps</code> in <code>cloud/manifest/apps.go</code>, in exact bijection with the 129 <code>plugin/<app>/openapi.json</code> subsets, gated by <code>plugin/gen-app-cmds</code> |</p>
|
|
<p>The manifest is <strong>curation, not a registry</strong>: it cannot invent a capability, because <code>publish.py</code> refuses in both directions — a served name nobody has grouped fails the publish, and a grouped name nothing serves fails it too. The nine domains are <code>identity</code> (16) · <code>intelligence</code> (14) · <code>data</code> (14) · <code>streams</code> (12) · <code>observability</code> (5) · <code>commerce</code> (18) · <code>platform</code> (14) · <code>applications</code> (24) · <code>chain</code> (3). Every count here is measured, and every one of them moves; read them as a shape, and take the number from the gate.</p>
|
|
<p><strong>Capability ≠ app.</strong> Some apps serve more than one <code>/v1</code> product — <code>platform</code> answers <code>/v1/platform</code> and <code>/v1/build</code>, <code>git</code> answers <code>/v1/git</code> and <code>/v1/runner</code> — and some addresses are served by the host itself rather than by any plugin (<code>GET /v1/openapi.json</code>, <code>GET /v1/openapi/commands</code>) — so a sweep of <code>plugin/*/openapi.json</code> alone under-reports the served set, and reading a capability count as a binary count is always wrong.</p>
|
|
<p>A fourth number exists and is not a capability count: operations carrying the <code>compat</code> tag are DROPPED from the published document by <code>publish.py</code>, so a wire-compatibility dialect never mints a product name.</p>
|
|
<h4>1.2 — Declared-but-unserved names are drift, and are named</h4>
|
|
<p>A name in the manifest that <code>cloud</code> does not serve is drift, and each one is a rename or a consolidation with a commit behind it: <code>sentry</code>→<code>sentinel</code>, folded under <code>/v1/o11y/sentinel</code>; <code>automations</code>→<code>auto</code>; <code>balancers</code>/<code>vpcs</code>/<code>cloud</code> deleted with their apps; four speech names folded into <code>/v1/audio/*</code>; and <code>health</code>, which was never a product, because per-app liveness is auto-mounted.</p>
|
|
<p>The instructive one was <code>edge</code>, and it is closed. <code>GET /v1/edge</code> named a POSITION rather than a product, and four unrelated things wore the word: the on-device inference runtime a customer runs on their own machine, which has no cloud prefix and never should; the public catalogue cache; the gateway's policy role; and the zero-trust fabric's edge-routers. The correction was the one this section asked for — the routers are addressed as what they are, <code>/v1/network/routers</code> — so the row is gone, <code>/v1/edge</code> 404s at every depth, and that is the right answer rather than a missing product.</p>
|
|
<h3>2 — The language seam is the ZAP wire, NEVER FFI</h3>
|
|
<p>Go and Rust components compose over <strong>ZAP</strong> (network or local socket), each a clean single-language binary. Go <code>cloud</code> ⟷ Rust <code>engine</code>/<code>dev</code>/<code>cli</code> never link each other's code; they exchange ZAP frames. The wire format those frames are in — what a ZAP message <em>is</em>, field offsets and all — is defined once, language- agnostically, in <strong><code>zap-proto/zap-spec</code></strong>. The runtimes implement it: <code>zap-proto/go</code>, <code>@zap-proto/zap</code> for TypeScript, and the <code>zapwire</code> crate in <code>hanzoai/zap</code> for Rust, which is cross-checked against Go's bytes.</p>
|
|
<ul><li>No cross-toolchain build: each binary is compiled by one toolchain, and a</li></ul>
|
|
<p> release matrix is the sum of the two rather than their product.</p>
|
|
<ul><li>Language becomes an internal detail of each box; the boxes stay orthogonal and</li></ul>
|
|
<p> composable. Don't fuse — <strong>bridge</strong>.</p>
|
|
<h3>3 — Distribution: one contract → N bindings → thin clients</h3>
|
|
<p>The direction of generation is one-way and starts in the code. <code>cloud</code> emits <code>openapi.yaml</code> from its own live routers (the weave of the 123 per-app subsets); <code>publish.py</code> in <code>hanzoai/openapi</code> derives <code>hanzo.yaml</code> from that emission at one pinned release, applying <code>capabilities.yaml</code> only as the domain grouping. <strong>Nothing is authored downstream of the code</strong>: to change the API you change a route in <code>cloud</code>.</p>
|
|
<pre><code>cloud/openapi.yaml (emitted from the live routers — 123 subsets, woven)
|
|
│ publish.py, at one pinned release ↓ (+ capabilities.yaml: grouping only)
|
|
hanzo.yaml (the ONE published contract — /v1 over HTTP + ZAP)
|
|
│ generate ↓
|
|
go-sdk · rust-sdk · js-sdk (language bindings — HIP-0040; rust hand-kept)
|
|
│
|
|
hanzo — the control CLI (apps/deploy/login/…) → @hanzo/cli
|
|
dev — the coding agent (codex fork) → @hanzo/dev
|
|
|
|
zap-proto/zap-spec an INPUT, not an output: the ZAP wire format itself,
|
|
hand-authored and language-agnostic (§2)</code></pre>
|
|
<ul><li><strong>The CLI is a client, never the server.</strong> It speaks HTTP or ZAP to a <em>live</em></li></ul>
|
|
<p> cloud — prod, a laptop host, or a customer self-host — and <strong>never imports <code>hanzoai/cloud</code></strong> (that coupling is what makes a control tool carry a fleet). The rule holds by construction today: <code>hanzo</code> is Rust and links no Go.</p>
|
|
<ul><li><strong>CLI language = Rust</strong>, one thin binary per tool. <code>hanzo</code> and <code>dev</code> are two</li></ul>
|
|
<p> Rust binaries sharing an auth model (HIP-0111 OIDC PKCE S256) but, today, not yet a crate: there is no shared <code>hanzo-client</code>. One client crate under both remains the target; nothing about the seam depends on reaching it.</p>
|
|
<ul><li><strong>Distribution is one harness, many channels:</strong> per-platform prebuilt binaries</li></ul>
|
|
<p> on GitHub Releases, fetched by ONE script. <code>cli/install.sh</code> is the single implementation of "fetch a Hanzo binary" — it detects the platform, verifies the asset's sha256, and refuses loudly on a platform we do not publish. The channels drive that one script rather than carrying copies of it: <code>hanzo.sh</code> (curl|sh) overrides three variables per tool, and <code>@hanzo/cli</code>/<code>@hanzo/dev</code> install it from a postinstall step whose <code>bin</code> shim execs the real binary and gets out of the way. One binary per tool, N channels (HIP-0041).</p>
|
|
<h3>3a — Schemas are co-located, never a monorepo</h3>
|
|
<p>A capability's <code>.zap</code> wire schema lives <strong>alongside the product that implements it</strong> — the contract evolves with its code in one PR, versioned as a unit. There is <strong>no central <code>hanzoai/zap</code> schema repo</strong>; centralizing decouples contract from implementation (drift) and braids every product's contract into one place.</p>
|
|
<ul><li>Shared primitives — the message layout every schema is expressed in — live in</li></ul>
|
|
<p> <code>zap-proto/zap-spec</code>, one level below any capability, the same way an OpenAPI document depends on JSON Schema rather than on a shared components file. There is no <code>openapi/shared</code>; an earlier draft cited one, and nothing by that name exists.</p>
|
|
<ul><li>Discovery for cross-service consumers is a <strong>generated union</strong>, the ZAP analog</li></ul>
|
|
<p> of <code>hanzo.yaml</code> — not a monorepo.</p>
|
|
<ul><li><code>.zap</code> and OpenAPI are two transports of the SAME <code>/v1</code> contract, and both</li></ul>
|
|
<p> derive from the implementing code, never from each other and never from the manifest (<code>capabilities.yaml</code> groups names for a reader and declares no route). Do not hand-maintain them separately — one contract → HTTP + ZAP + SDKs, all generated.</p>
|
|
<ul><li><code>hanzoai/zap</code> stays the Hanzo ZAP <strong>runtime/sidecar</strong> (SQL/KV/Datastore bridge),</li></ul>
|
|
<p> never a schema store.</p>
|
|
<h3>4 — Org by capability, not by language</h3>
|
|
<p>Everything canonical under <strong><code>hanzoai/<product></code></strong> (<code>hanzoai/cloud</code> Go, <code>hanzoai/engine</code> Rust, <code>hanzoai/dev</code> Rust, <code>hanzoai/cli</code> Rust). NO <code>hanzo-go</code>/<code>hanzo-rs</code> orgs. Users never know or care which language answered — because the org is product-first and the wire is uniform, <strong>not</strong> because the languages are fused.</p>
|
|
<h3>5 — Deploy: the declared state is the only writer</h3>
|
|
<p><strong>One writer, and for a first-party service it is git, not the cluster.</strong> The image a service runs is declared in the universe repository's operator App CR (<code>hanzo.ai/v1</code>, <code>infra/k8s/operator/crs/<service>.yaml</code>) and reconciled by Hanzo CD with <code>selfHeal</code>. A rollout is therefore a COMMIT that moves the tag in that file; the operator reconciles from it.</p>
|
|
<p>This inverts what an earlier draft of this section specified. It said deploys merge-patch the CR's <code>.spec.image</code> from an embedded <code>clients/paas</code>. Two things are wrong with that. <code>clients/paas</code> does not exist — the code is <code>cloud/apps/platform/rollout.go</code>. And its <code>releaseService</code> <strong>refuses that patch by name</strong>: under <code>selfHeal</code> a patch is reverted on the next sync, so the release would look applied and then silently roll back. It validates first (DNS-1123 name, strict-semver image, the App exists in the namespace) so the refusal is specific, and its error names the remedy: commit the tag to that file.</p>
|
|
<p>A green pipeline therefore ends at a minted release tag — a receipt for a built, smoke-passed image — and NOT at a live rollout. That pair is not a broken build; it is an image with no declared state pointing at it yet. The mechanism this enforces is exactly "no second deployer": a CR patch plus a git commit are two writers for one fact, and composing them best-effort hides their disagreement. The <code>hanzo</code> CLI and the platform UI drive the commit; neither writes to a cluster.</p>
|
|
<h3>6 — Decentralized: the network is the substrate</h3>
|
|
<p><code>hanzo.network</code> is the Hanzo Node fleet — a Rust peer-to-peer node for decentralized AI compute coordination (HIP-0020), a different artifact from the Go host and its plugins. The two meet at compute, not at a shared process: a box on the network contributes metered capacity that the cloud bills against (HIP-0121) and that earns its operator rewards (HIP-0096), and a mainnet validator's own box is native rather than rented.</p>
|
|
<p>What makes this OSS AI cloud is that the same 123 apps run anywhere: anyone runs them on their own machine, brings their own GPU or K8s, and public + OSS workloads run free on public nodes. <strong>They are not one binary.</strong> The fused build that once linked every subsystem into <code>cmd/cloud</code> was deleted; what a self-hoster runs is the light host plus whichever plugins they want, which is precisely why running a subset is cheap — an app you do not mount is a binary you never build. Read the "single binary" of earlier drafts as "one artifact per app, one command to run them", never as one link step over the fleet.</p>
|
|
<h2>Consequences</h2>
|
|
<ul><li>Closes the <code>cmd/hanzo</code> question (#10), though not the way it was closed on</li></ul>
|
|
<p> paper. <code>cmd/hanzo</code> and the server-multicall rung were <strong>deleted</strong>, not folded: a per-app binary is now the only plugin source. The thin control CLI is the Rust <code>hanzo</code>.</p>
|
|
<ul><li>SDKs (HIP-0040) and CLI (HIP-0041) are now defined as *derivations of</li></ul>
|
|
<p> <code>hanzo.yaml</code>*, not independent artifacts.</p>
|
|
<ul><li>Sites (<code>docs.hanzo.ai</code>, <code>hanzo.ai</code>, <code>hanzo.app</code>) present this model verbatim:</li></ul>
|
|
<p> category-first capability surface, the network story, the self-host path. The reference is regenerated from the document on every build — one page per PRODUCT, not per app, and none of it authored — so a capability's page appears when its route does and cannot be written ahead of it.</p>
|
|
<h2>References</h2>
|
|
<ul><li>HIP-0106 The Hanzo Plugin Contract · HIP-0114/0120 ZAP Transport ·</li></ul>
|
|
<p> HIP-0040 SDKs · HIP-0041 CLI · HIP-0111 IAM Authentication · HIP-0020 Blockchain Node · HIP-0096 Compute Rewards · HIP-0121 BYO Compute.</p>
|
|
<ul><li><code>capabilities.yaml</code>, <code>publish.py</code> and <code>hanzo.yaml</code> in the <strong><code>hanzoai/openapi</code></strong></li></ul>
|
|
<p> repository · <code>manifest/apps.go</code> and <code>cmd/cloud/main.go</code> in <code>hanzoai/cloud</code> · <code>hanzoai/platform</code> · <code>zap-proto/zap-spec</code> · <code>hanzoai/zap</code>.</p>
|
|
<ul><li>HIP-0106 described the fused single-binary predecessor and is <strong>Superseded</strong></li></ul>
|
|
<p> by HIP-0106. Do not read it as current architecture.</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-0127.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
|
|
</footer>
|
|
</div></body></html> |