mirror of
https://github.com/hanzoai/skills.git
synced 2026-11-19 00:47:36 +00:00
306 lines
32 KiB
HTML
306 lines
32 KiB
HTML
<!doctype html>
|
|
<html lang="en"><head>
|
|
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
|
|
<title>hip-0120</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-0120.md">
|
|
|
|
<link rel="icon" href="/favicon.svg">
|
|
<link rel="canonical" href="https://hanzoskills.com/hip-0120">
|
|
</head>
|
|
<!-- Reading this with a machine? Every page here is also plain markdown.
|
|
This one: https://hanzoskills.com/hip-0120.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-0120</h1><p class="lede">HIP-120: ZAP-Native Transport & gRPC Elimination. Status Final. Hanzo architectural specification.</p><h1>HIP-0120: ZAP-Native Transport & gRPC Elimination</h1>
|
|
<h2>Abstract</h2>
|
|
<p>Hanzo has exactly one inter-service transport: <strong>ZAP</strong>, the Hanzo-native binary wire (<code>github.com/zap-proto/*</code>). This HIP makes the corollary a platform-wide standard:</p>
|
|
<blockquote><p><strong>A Hanzo service speaks ZAP, HTTP, or WS. It never speaks gRPC.</strong></p></blockquote>
|
|
<p>The three permitted protocols are complete for every wire Hanzo needs — ZAP for inter-service and inter-VM traffic (HIP-0106, HIP-0114), HTTP for the external request/response edge and HTTP-semantics-over-ZAP internally, and WS for long-lived bidirectional client streams. gRPC is a fourth transport with its own HTTP/2 framing, its own code-generated stub layer, and its own mutable-message data model; admitting it would violate "one and only one way to do everything" and drag <code>google.golang.org/grpc</code> — a large dependency and attack surface — into the graph.</p>
|
|
<p>This HIP specifies: the rule and its RFC 2119 force; the three permitted protocols; <strong>OTLP-over-ZAP</strong> (the shipped exemplar — OpenTelemetry spans ride the ZAP wire to the o11y collector, standard OTLP protobuf payload, ZAP transport, never OTLP-HTTP <code>:4318</code> or OTLP-gRPC <code>:4317</code>); the <strong>pb2zap</strong> source-migration path; the design decision that there is <strong>no transparent runtime gRPC-over-ZAP shim</strong>; and the <strong>canonical conformance gate</strong> — zero first-party <code>google.golang.org/grpc</code> imports, enforced by grep over <code>.go</code> source, not by <code>go.mod</code>.</p>
|
|
<p>The standard is already shipped across four repositories — <code>cloud</code>, <code>gateway</code>, <code>visor</code>, <code>ai</code> — in four commits (see Reference Implementation). First-party gRPC imports across all four are <strong>zero</strong>. What remains is never-dialed transitive library code, honestly accounted for in <strong>Residual & Conformance</strong>.</p>
|
|
<h2>Motivation</h2>
|
|
<h3>One transport, not two</h3>
|
|
<p>HIP-0106 fixed ZAP as the inter-subsystem contract of the unified <code>cloud</code> binary: every subsystem ships a <code>.zap</code> schema, <code>zapc</code> generates the bindings, and calls resolve to direct Go method dispatch when co-resident or ZAP RPC when split. HIP-0114 fixed ZAP as the inter-VM cognitive transport for Thinking Chains. Both rest on the same premise: <strong>ZAP is the one Hanzo wire.</strong> A second RPC transport — gRPC — is not a convenience, it is a fork in the road, and "if there are two ways to do something, one is wrong." gRPC is the wrong one: Hanzo already has a native, versioned, schema-driven transport that spans in-process, node-local, and cross-node hops with one set of generated types.</p>
|
|
<h3>ZAP is zero-copy; gRPC's message model is not</h3>
|
|
<p>ZAP splits a message into three values with distinct lifetimes: an <strong>Input</strong> (built once, write-only), a <code>[]byte</code> (the transport frame), and a <strong>View</strong> (read many times, zero-copy over the frame's backing bytes). Protobuf/gRPC collapses these into a single <strong>mutable message struct</strong> that is built, read, and mutated in place. The mutable model forces allocation and copy at every boundary and is precisely the model ZAP rejects. Bolting gRPC onto a ZAP stack re-imports the cost ZAP was built to remove.</p>
|
|
<h3>The edge is JWT→ZAP; gRPC would need a parallel identity path</h3>
|
|
<p>Per HIP-0112, external traffic terminates at <code>ingress → gateway</code>: TLS ends at ingress, the gateway validates the IAM JWT, strips client-supplied identity headers, and mints trusted ones. Every hop <em>after</em> the gateway rides ZAP with the minted identity already attached. A gRPC service would need its own HTTP/2 metadata-based auth plumbing and its own interceptor chain kept in lockstep with the gateway's header contract — a second identity path to drift out of sync. One transport means one identity path.</p>
|
|
<h3>Supply-chain surface</h3>
|
|
<p><code>google.golang.org/grpc</code> pulls an HTTP/2 framing stack, connection/balancer machinery, and the protoc-gen-go-grpc stub layer; the OpenTelemetry gRPC exporters (<code>otlptracegrpc</code>, <code>otlpmetricgrpc</code>) and <code>otelgrpc</code> pull it further into telemetry. Each import is transitive CVE exposure and dependency weight for a wire Hanzo does not use. Eliminating first-party gRPC shrinks the graph to what Hanzo actually dials.</p>
|
|
<h2>Specification</h2>
|
|
<p>The keywords MUST, MUST NOT, SHALL, SHOULD, MAY are used per RFC 2119.</p>
|
|
<h3>1. The rule</h3>
|
|
<ul><li>A Hanzo service <strong>MUST NOT</strong> import <code>google.golang.org/grpc</code> (or a generated</li></ul>
|
|
<p> <code>*_grpc.pb.go</code> stub) in first-party source.</p>
|
|
<ul><li>A Hanzo service <strong>MUST NOT</strong> expose a gRPC server or dial a gRPC client for</li></ul>
|
|
<p> traffic between Hanzo services.</p>
|
|
<ul><li>A Hanzo service <strong>MUST</strong> carry inter-service and inter-VM traffic over ZAP,</li></ul>
|
|
<p> and <strong>MAY</strong> additionally terminate HTTP and WS at the external edge (§2).</p>
|
|
<ul><li>Where an external dependency is only reachable over a gRPC SDK, the service</li></ul>
|
|
<p> <strong>MUST</strong> prefer the provider's REST/HTTP surface and hand-roll a <code>net/http</code> client when a maintained REST client is unavailable (§Rationale; the <code>visor</code>/<code>ai</code> GCP compute adapters are the reference). This keeps the gRPC transport out of Hanzo's first-party graph.</p>
|
|
<h3>2. The three permitted protocols</h3>
|
|
<p>| Protocol | Where it applies | Canonical implementation | |----------|------------------|--------------------------| | <strong>ZAP</strong> | The one internal wire: inter-subsystem (HIP-0106), inter-VM (HIP-0114), service-to-service RPC. Native binary frames with an X-Wing PQ-KEM handshake; carries build-once <code>Input</code> → <code>[]byte</code> → read-many zero-copy <code>View</code>. | <code>github.com/zap-proto/go</code> (codec/runtime, v1.3.0), <code>github.com/zap-proto/zip</code> (web framework, v1.2.1), <code>github.com/zap-proto/http</code> (HTTP semantics over the ZAP wire, v0.2.0) | | <strong>HTTP</strong> | The external request/response edge (JSON in/out, terminated by <code>ingress → gateway</code> per HIP-0112). Internally, HTTP <em>semantics</em> ride the ZAP wire via <code>zap-proto/http</code> — the same request/response shape, ZAP frames underneath. | <code>zap-proto/http</code>, <code>hanzoai/zip</code> handlers; stdlib <code>encoding/json</code>(/v2) at the edge | | <strong>WS</strong> | Long-lived bidirectional client streams at the external edge; the ZAP-carried variant for internal streaming. | <code>zap-proto/ws</code>, <code>zap-proto/web</code> |</p>
|
|
<p>The rest of the ZAP family (<code>zap-proto/zapd</code> router, <code>zap-proto/zap-spec</code>) are part of the same ecosystem. <strong>Note the namespace:</strong> the ZAP <em>transport and framework</em> live under <code>github.com/zap-proto/*</code>; this is distinct from <code>hanzoai/zap</code>, the Hanzo SQL/KV/Datastore sidecar, which keeps the <code>hanzoai</code> namespace and is not a transport.</p>
|
|
<p>gRPC appears in none of these rows. There is no fourth row.</p>
|
|
<h3>3. OTLP-over-ZAP (shipped exemplar)</h3>
|
|
<p>Telemetry is the canonical demonstration that a protocol conventionally bound to gRPC can ride ZAP with no semantic change. OpenTelemetry ships an <code>otlptrace.Client</code> interface whose default wires are OTLP-over-gRPC (<code>:4317</code>) and OTLP-over-HTTP (<code>:4318</code>). Hanzo implements a <strong>third</strong> client whose wire is ZAP.</p>
|
|
<p><code>cloud/zaptrace/zaptrace.go</code> is an <code>otlptrace.Client</code> (compile-time asserted: <code>var _ otlptrace.Client = (*Client)(nil)</code>) whose transport is <code>github.com/zap-proto/http</code>:</p>
|
|
<ul><li><strong>Payload is unchanged.</strong> Spans are marshaled as standard OTLP protobuf. Only</li></ul>
|
|
<p> the transport differs — the collector receives a byte-identical <code>ExportTraceServiceRequest</code>.</p>
|
|
<ul><li><strong>Wire is ZAP.</strong> <code>UploadTraces</code> builds a <code>fasthttp</code> <code>POST http://zap/v1/traces</code></li></ul>
|
|
<p> with <code>Content-Type: application/x-protobuf</code> and sends it through a pooled <code>zaphttp.Transport</code>. The collector's ZAP receiver (<code>zapreceiver</code>) terminates the frame at <strong><code>:4319</code></strong> and writes to <code>hanzoai/datastore</code>. Spans travel OTLP-over-<strong>ZAP</strong> — <strong>never</strong> OTLP-HTTP <code>:4318</code>, <strong>never</strong> OTLP-gRPC <code>:4317</code>.</p>
|
|
<ul><li><strong>The envelope is hand-encoded to stay gRPC-free.</strong> The request is a single</li></ul>
|
|
<p> <code>repeated ResourceSpans resource_spans = 1</code>, so <code>UploadTraces</code> appends each <code>ResourceSpans</code> under field 1 with <code>protowire</code> directly from the grpc-free <code>go.opentelemetry.io/proto/otlp/trace/v1</code> messages. This deliberately avoids the generated <code>collector/trace/v1.ExportTraceServiceRequest</code> type, whose sibling <code>trace_service_grpc.pb.go</code> (shipped with <strong>no build tag</strong>) would drag <code>google.golang.org/grpc</code> back into the module graph. The hand-encoding is byte-identical to the generated marshaler — proven by <code>zaptrace_test.go</code>, which stands up a real <code>zaphttp.Server</code> and decodes the received body with the canonical <code>collector/trace/v1</code> type.</p>
|
|
<ul><li><strong>Selection is by environment; no code branches per deploy.</strong></li></ul>
|
|
<p> <code>cloud/cmd/cloud/telemetry.go</code> installs exactly one tracer provider:</p>
|
|
<ul><li><code>OTEL_EXPORTER_ZAP_ENDPOINT</code> set (or unset with a ZAP default of</li></ul>
|
|
<p> <code>localhost:4319</code>) → spans ride ZAP.</p>
|
|
<ul><li>Only a legacy <code>OTEL_EXPORTER_OTLP_*</code> endpoint set → spans ride OTLP-HTTP</li></ul>
|
|
<p> (the interop/loopback fallback used while the standalone collector is folded in). This fallback is HTTP, never gRPC.</p>
|
|
<ul><li><strong>Composition-root ownership.</strong> After installing the ZAP provider, <code>cloud</code></li></ul>
|
|
<p> unsets <code>OTEL_EXPORTER_OTLP_TRACES_ENDPOINT</code> / <code>OTEL_EXPORTER_OTLP_ENDPOINT</code> so an embedded subsystem (notably <code>hanzoai/ai</code>'s <code>object.InitTelemetry</code>) cannot install a second, competing OTLP provider that would strand later spans on <code>:4318</code>. Exactly one provider, one wire, deterministically.</p>
|
|
<p>Scope note (honest): <strong>traces</strong> ride ZAP today. A ZAP-native metrics/logs exporter is roadmap (§Residual & Conformance); the OTLP metrics/logs exporters are the current transitive-grpc source, never a dialed gRPC channel.</p>
|
|
<h3>4. The pb2zap migration path</h3>
|
|
<p>Porting a protobuf/gRPC call site to ZAP is a <strong>source-level</strong> transformation, accelerated by <code>github.com/zap-proto/pb2zap</code> — a syntactic <code>go/ast</code> codemod (a one-time migration tool, <strong>not</strong> a runtime bridge). For each construction site it:</p>
|
|
<ol><li>Rewrites protobuf construction <code>&x_pb.Req{F: v}</code> into the ZAP build-once</li></ol>
|
|
<p> form <code>xwire.NewReq(xwire.ReqInput{F: v})</code>.</p>
|
|
<ol><li>Adds the generated <code>xwire</code> import and drops the now-unused <code>x_pb</code> import.</li><li><strong>Reports — never guesses —</strong> the read and mutate selectors it cannot</li></ol>
|
|
<p> mechanically transform (a field <em>read</em> becomes a <code>View</code> accessor; an in-place <em>mutate</em> has no ZAP equivalent and must be restructured by hand).</p>
|
|
<p>pb2zap moves the mechanical 80%; the reported read/mutate sites are finished by hand against the ZAP <code>View</code>/<code>Input</code> types. There is no automatic path for a mutate-in-place site because ZAP has no mutable message (§Rationale).</p>
|
|
<h3>5. Conformance gate</h3>
|
|
<p>The <strong>canonical, CI-enforceable gate</strong> is: <strong>zero first-party <code>google.golang.org/grpc</code> imports.</strong></p>
|
|
<pre><code class="lang-sh"># MUST return no rows for a conforming repo:
|
|
grep -rl '"google.golang.org/grpc' --include='*.go' . | grep -v /vendor/</code></pre>
|
|
<p>Verified empty for <code>cloud</code>, <code>gateway</code>, <code>visor</code>, and <code>ai</code>.</p>
|
|
<p>The gate is deliberately <strong>not</strong> <code>grep google.golang.org/grpc go.mod</code>. That command is non-empty and <strong>cannot</strong> be driven to zero while Hanzo depends on the upstream OpenTelemetry OTLP-HTTP exporter and the Gemini SDK, both of which list gRPC as an indirect requirement they never dial (§Residual & Conformance). A go.mod gate would be permanently red for reasons unrelated to whether any Hanzo code speaks gRPC. The import gate measures the real invariant: <strong>does first-party Hanzo code dial or serve gRPC? No.</strong></p>
|
|
<p>The conformance gate is a grep over source, suitable for CI. A regression — a new dependency that imports <code>google.golang.org/grpc</code> first-party, or a "convenient" gRPC client added to a service — fails the gate deterministically, where a human reviewer might miss it in a large diff.</p>
|
|
<h2>Residual & Conformance</h2>
|
|
<p><strong>Enforceable gate: PASS.</strong> First-party <code>google.golang.org/grpc</code> imports across <code>cloud</code>, <code>gateway</code>, <code>visor</code>, <code>ai</code> = <strong>zero</strong> (verified by the §5 grep). No Hanzo first-party code serves or dials gRPC.</p>
|
|
<p><strong>Residual go.mod grpc is never-dialed transitive/indirect,</strong> and is <em>not</em> a conformance signal. Per repo:</p>
|
|
<p>| Repo | <code>grpc</code> in go.mod | Source (never dialed by first-party code) | |------|------------------|-------------------------------------------| | <code>cloud</code> | <code>v1.81.1 // indirect</code> (+ <code>otelgrpc v0.67.0 // indirect</code>) | Embedded siblings: <code>hanzoai/ai</code>, <code>hanzoai/o11y</code> (intrinsically an OTLP/gRPC <em>collector</em>, so its gRPC is definitional to the receiver, not a Hanzo client dial), <code>hanzoai/base</code> (GCS gRPC transport). <code>zaptrace</code> itself is grpc-free. | | <code>gateway</code> | <code>v1.80.0 // indirect</code> (+ <code>otelgrpc v0.67.0 // indirect</code>) | <code>krakend-pubsub</code>'s hardcoded <code>gocloud.dev/pubsub/gcppubsub</code> blank import (a GCP Pub/Sub driver Hanzo does not use), legacy build only. | | <code>visor</code> | <code>v1.80.0 // indirect</code> | OTLP-HTTP telemetry exporter: <code>telemetry → otlpmetrichttp → internal/oconf → grpc</code>. HTTP transport; no channel dialed. | | <code>ai</code> | <code>v1.81.1 // indirect</code> | OTLP-HTTP exporter (<code>object → otlptracehttp → internal/otlpconfig → grpc</code>) and the Gemini SDK <code>google.golang.org/genai</code> (a <em>direct</em> dep at <code>v1.10.0</code> whose HTTP backend transitively requires grpc). Neither dials a gRPC channel. |</p>
|
|
<p><strong>Gate blind spot, stated honestly.</strong> The import grep catches direct first-party gRPC use; it does <strong>not</strong> catch a first-party import of a <em>third-party</em> SDK that internally dials gRPC to an <strong>external</strong> provider. The mandate governs Hanzo's own inter-service wire — a third-party cloud provider's control-plane SDK is interop, not a Hanzo transport. The governing rule: where a REST/HTTP surface exists, the gRPC SDK MUST be replaced (done for GCP compute in <code>visor</code>/<code>ai</code>); where none exists, the dependency is a documented exception that never targets a Hanzo service. No such exception exists in-tree today (verified: <code>visor</code> carries no external gRPC-dialing SDK).</p>
|
|
<p><strong>Path to literal-zero go.mod (future work).</strong> Reaching an empty <code>grep grpc go.mod</code> requires eliminating the <em>upstream</em> transitive pulls, none of which is a Hanzo gRPC conversation:</p>
|
|
<ol><li><strong>ZAP-native metrics/logs exporter.</strong> Extend the <code>zaptrace</code> pattern</li></ol>
|
|
<p> (protowire hand-encode over <code>zap-proto/http</code>) to a metrics and logs exporter, retiring <code>otlpmetrichttp</code>/<code>otlptracehttp</code> — the OTLP-HTTP internal config that carries the indirect grpc in <code>visor</code> and <code>ai</code>.</p>
|
|
<ol><li><strong>Raw-HTTP Gemini client (<code>ai</code>).</strong> Replace <code>google.golang.org/genai</code> with a</li></ol>
|
|
<p> <code>net/http</code> client against the <code>generativelanguage</code> REST surface, removing the last direct dependency that transitively requires grpc.</p>
|
|
<ol><li><strong>Embedded O11y/GCS (<code>cloud</code>).</strong> The <code>o11y</code> collector is an OTLP/gRPC</li></ol>
|
|
<p> <em>receiver</em> by definition; its grpc is not a client dial and is out of scope for the client-side mandate. <code>hanzoai/base</code> GCS transport is a separate GCS- over-REST question tracked with the compute work.</p>
|
|
<p>Until then, the standard's conformance is measured where it is real and enforceable: <strong>zero first-party gRPC imports.</strong></p>
|
|
<h2>References</h2>
|
|
<ul><li><a href="./hip-0106-hanzo-plugin-contract.md">HIP-0106: The Hanzo Plugin Contract</a> — ZAP as the inter-subsystem contract; the canonical Hanzo Go stack; the "no <code>.capnp</code> in Hanzo-authored source" policy.</li><li>HIP-0112: Cloud Topology — <code>ingress → gateway → services</code>; the external edge where HTTP/WS terminate and identity headers are minted.</li><li><a href="./hip-0114-zap-inter-vm-cognitive-transport.md">HIP-0114: ZAP — Inter-VM Cognitive Transport for Thinking Chains</a> — ZAP as the inter-VM transport; "ZAP transports; proofs commit; receipts settle; VMs execute."</li><li><code>github.com/zap-proto/{go,zip,http,ws,web,zapd,zap-spec}</code> — the ZAP transport and framework ecosystem.</li><li><code>github.com/zap-proto/pb2zap</code> — the syntactic <code>go/ast</code> protobuf→ZAP migration codemod.</li><li>OpenTelemetry OTLP specification — the span payload format ZAP carries unchanged (transport-substituted, not payload-modified).</li></ul>
|
|
<h3>6. Same machine is a unix socket, not a network hop</h3>
|
|
<p>Cloud is one binary running plugins. When two of them sit on the same machine — which is the normal case, not the exception — a TCP hop to localhost is pure overhead: a syscall path, a checksum, a port, and a loopback round trip to reach a process sharing the same kernel.</p>
|
|
<p><strong>ZAP over a unix socket is the PREFERRED transport for any plugin-to-plugin call inside cloud.</strong> Network ZAP remains correct where the peer is genuinely on another machine.</p>
|
|
<p>The rule, in order:</p>
|
|
<ol><li><strong>Same process</strong> — a direct call. No transport at all.</li><li><strong>Same machine</strong> (plugin↔plugin, sidecar↔host) — <strong>ZAP over UDS</strong>.</li><li><strong>Different machine</strong> — ZAP over the network.</li></ol>
|
|
<p>A socket path is also an authorization boundary: filesystem permissions gate who may connect, with no port to scan and no interface to accidentally bind. A service reachable only through a socket in its own namespace cannot be reached from another pod at all.</p>
|
|
<p><strong>Shipped:</strong> <code>cloud/rpc.go</code> — the internal plane over <code>net.Listen("unix", path)</code> with a 200ms dial probe to detect a live peer before binding, and <code>dial.go</code>/<code>serve.go</code> moving callers onto it (branch <code>feat/zap-uds-internal-plane</code>).</p>
|
|
<p><strong>What UDS cannot do, so it is not claimed:</strong> a per-node DaemonSet reading <code>/var/log/pods</code> does not share a filesystem namespace with a central service. That path stays network ZAP unless the reader becomes co-located with its consumer. UDS is chosen because processes are co-located; it never makes them so.</p>
|
|
<h2>Copyright</h2>
|
|
<p>Copyright and related rights waived via <a href="https://creativecommons.org/publicdomain/zero/1.0/">CC0</a>.</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-0120.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
|
|
</footer>
|
|
</div></body></html> |