mirror of
https://github.com/hanzoai/skills.git
synced 2026-11-19 00:47:36 +00:00
402 lines
37 KiB
HTML
402 lines
37 KiB
HTML
<!doctype html>
|
||
<html lang="en"><head>
|
||
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
|
||
<title>hip-0105</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-0105.md">
|
||
|
||
<link rel="icon" href="/favicon.svg">
|
||
<link rel="canonical" href="https://hanzoskills.com/hip-0105">
|
||
</head>
|
||
<!-- Reading this with a machine? Every page here is also plain markdown.
|
||
This one: https://hanzoskills.com/hip-0105.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-0105</h1><p class="lede">HIP-105: In-Process Extension Runtime Standard. Status Final. Hanzo architectural specification.</p><h1>HIP-0105: In-Process Extension Runtime Standard</h1>
|
||
<h2>Abstract</h2>
|
||
<p>This proposal defines how user-supplied code is loaded and executed <strong>inside a running Hanzo Go service</strong> — distinct from the K8s-scale FaaS surface in HIP-0060. The same service binary can host extensions in four engines — <strong>native Go</strong>, <strong>goja</strong> (pure-Go JS interpreter), <strong>wazero</strong> (pure-Go WASM runtime), and <strong>v8go</strong> (V8 via cgo) — and pick the right one per extension via an <code>extension.json</code> manifest. The Runtime interface is one type with four implementations; switching engines is a one-line manifest change.</p>
|
||
<p><strong>Reference implementation</strong>: <code>~/work/hanzo/base/plugins/{extruntime,gojavm,wasmvm,v8vm}</code> (<a href="https://github.com/hanzoai/base/tree/main/plugins">hanzoai/base/plugins</a>, landed 2026-05-19). Full benchmark write-up at <code>~/work/hanzo/base/docs/EXTENSIONS_BENCHMARK.md</code>.</p>
|
||
<h2>Motivation</h2>
|
||
<p>Hanzo services regularly need to run <strong>user-supplied code</strong> without spinning up a Knative pod or shelling out to a sidecar:</p>
|
||
<ul><li>Per-record validators and computed fields in Hanzo Base</li><li>Per-org policy / authz rules in Hanzo IAM and Gateway</li><li>Custom prompt transformers in the LLM Gateway</li><li>Tool implementations for agents (MCP-side tool functions)</li><li>Webhook body transformations</li><li>Custom CRDT merge resolvers</li><li>Per-tenant feature flags evaluated against context</li></ul>
|
||
<p>The naïve options are all bad:</p>
|
||
<ol><li><strong>Run user code in the host Go process directly</strong> — no sandbox, one panic</li></ol>
|
||
<p> kills the service for every tenant.</p>
|
||
<ol><li><strong>Shell out to a Node.js / Python subprocess</strong> — process spawn cost is</li></ol>
|
||
<p> milliseconds, pipes are bytes, memory floor is tens of megabytes per tenant.</p>
|
||
<ol><li><strong>Knative FaaS</strong> (HIP-0060) — right answer for bursty inference workloads</li></ol>
|
||
<p> with seconds of work; wrong answer for a hot-path validator that runs 1000 times per request.</p>
|
||
<p>The right answer is <strong>in-process</strong> with a <strong>sandbox boundary that scales to microseconds of overhead</strong>. WebAssembly provides this; modern JS engines provide it for JS specifically; pure-Go interpreters give a softer sandbox with zero binary cost. <strong>Each is correct for a different workload.</strong> This HIP codifies which is which.</p>
|
||
<h2>Specification</h2>
|
||
<h3>Runtime interface</h3>
|
||
<p>Every backing engine implements the same Go interface:</p>
|
||
<pre><code class="lang-go">package extruntime
|
||
|
||
type Runtime interface {
|
||
Name() string
|
||
Capabilities() Capabilities
|
||
Load(ctx context.Context, dir string) (Module, error)
|
||
Close() error
|
||
}
|
||
|
||
type Module interface {
|
||
Name() string
|
||
Runtime() string
|
||
Exports() []string
|
||
Invoke(ctx context.Context, fn string, payload []byte) ([]byte, error)
|
||
Close() error
|
||
}
|
||
|
||
type Capabilities struct {
|
||
AcceptsLanguages []string // ["go"] | ["js"] | ["wasm"]
|
||
HardSandbox bool // wazero, v8go: true; goja, native: false
|
||
Cgo bool // v8go: true; others: false
|
||
SupportsAbort bool // wazero, v8go: hard; goja: cooperative; native: false
|
||
}</code></pre>
|
||
<p><code>payload</code> and the Invoke result are <strong>JSON bytes</strong>. JSON is the wire format because (a) every backing engine can marshal it natively, (b) it's language-agnostic so AssemblyScript / Rust / Go / JS guests all see the same payload, and (c) the marshal cost is comparable across runtimes.</p>
|
||
<h3>Manifest</h3>
|
||
<p>Every extension carries a sibling <code>extension.json</code>:</p>
|
||
<pre><code class="lang-json">{
|
||
"name": "validate-email",
|
||
"version": "0.1.0",
|
||
"runtime": "wazero",
|
||
"module": "validate.wasm",
|
||
"exports": ["validate", "onUpdate"]
|
||
}</code></pre>
|
||
<p>Fields:</p>
|
||
<p>| Field | Required | Notes | |---|---|---| | <code>name</code> | yes | Unique within a host (e.g. <code><org>-<purpose></code>) | | <code>version</code> | yes | SemVer per global policy (HIP-0xxx semver-only) | | <code>runtime</code> | yes | One of <code>native</code>, <code>goja</code>, <code>wazero</code>, <code>v8go</code> | | <code>module</code> | conditional | Path to compiled artifact (<code><em>.wasm</code> for wazero, <code></em>.js</code> for goja/v8go). Not required for <code>native</code> runtime. | | <code>exports</code> | yes | List of function names callable via <code>Invoke</code> |</p>
|
||
<h3>Calling conventions</h3>
|
||
<h4>Go-native</h4>
|
||
<p>A native extension is a Go file that imports <code>github.com/hanzoai/base/plugins/extruntime</code> and registers itself at <code>init()</code>:</p>
|
||
<pre><code class="lang-go">extruntime.RegisterNative("validate-email", "validate", func(ctx context.Context, payload []byte) ([]byte, error) {
|
||
// ... return JSON bytes
|
||
})</code></pre>
|
||
<p>Compile-time linked. Zero abstraction cost beyond function pointer.</p>
|
||
<h4>Goja and V8go (JavaScript)</h4>
|
||
<p>The guest defines <code>globalThis.<fn></code> for each export:</p>
|
||
<pre><code class="lang-javascript">globalThis.validate = function(payload) {
|
||
return { ok: true, normalized: payload.email.toLowerCase() };
|
||
};</code></pre>
|
||
<p>Host unmarshals the JSON payload to a JS value, calls the function, and <code>JSON.stringify</code>s the result. No memory dance — JS engines own their heaps.</p>
|
||
<h4>Wazero (WebAssembly)</h4>
|
||
<p>The guest exports three functions in addition to its named exports:</p>
|
||
<pre><code>(func $__base_alloc (param i32) (result i32)) // ptr = alloc(len)
|
||
(func $__base_free (param i32 i32)) // free(ptr, len)
|
||
(func $<fn> (param i32 i32) (result i64)) // ret = fn(ptr, len)</code></pre>
|
||
<p><code><fn>(ptr, len)</code> returns an <code>i64</code> where the <strong>high 32 bits are the result pointer</strong> and the <strong>low 32 bits are the result length</strong> in the module's linear memory. The host calls <code>__base_free</code> on both the input buffer and the result buffer.</p>
|
||
<p>This convention is <strong>language-agnostic</strong> — AssemblyScript, Rust, Go (via TinyGo), Zig, and C can all target it. The <code>~/work/hanzo/base/plugins/extbench/fixtures/wazero-as/</code> sample shows the AssemblyScript implementation.</p>
|
||
<h3>Default behavior when ctx is cancelled</h3>
|
||
<p>| Runtime | Cancellation semantics | |---|---| | native | Cooperative — user code MUST check <code>ctx.Err()</code> | | goja | Cooperative — <code>vm.Interrupt()</code> fires only at function-call opcodes; tight numeric loops without yield points can resist abort | | wazero | Hard — <code>module.Close()</code> destroys the instance immediately; the runtime replenishes its pool from a background context | | v8go | Hard — <code>Isolate.TerminateExecution()</code> aborts within ~ms |</p>
|
||
<h3>Pool sizing</h3>
|
||
<p>Every runtime maintains a per-module pool of pre-warmed instances / contexts so per-invocation cost stays microsecond-scale. Each runtime exposes an env override. Anything <=0 or unparseable falls back to the default.</p>
|
||
<p>| Runtime | Env | Default | Notes | |---|---|---|---| | goja | <code>BASE_GOJAVM_POOL_SIZE</code> | 8 | Cheap per-pool-item (~9 KB Go heap); 8 is safe. | | wazero | <code>BASE_WASMVM_POOL_SIZE</code> | 8 | Wasm modules amortize compilation, so the pool exists to soak bursty hook traffic rather than to save instantiation. | | v8go | <code>BASE_V8VM_POOL_SIZE</code> | 8 | Sized for context pool, but see scale findings — v8go is <strong>NOT recommended for production</strong> at meaningful concurrency. | | pyvm | <code>BASE_PYVM_POOL_SIZE</code> | 4 | Each Python sub-interpreter is ~4.6 MB. Pool of 4 = ~18 MB baseline. Default tuned to balance per-module memory vs cold-start cost. | | starlark | <code>BASE_STARKVM_POOL_SIZE</code> | 8 | Pre-warmed <code>*starlark.Thread</code> instances. |</p>
|
||
<p>Native doesn't pool — functions are stateless Go calls.</p>
|
||
<h2>Benchmark data</h2>
|
||
<p>Run on Apple M1 Max, Go 1.26.3, median of 3 runs at <code>-benchtime=2s</code>. Workload: <code>validate(email, age)</code> — JSON in, JSON out, ~20 lines of logic.</p>
|
||
<h3>Throughput (lower ns/op is faster)</h3>
|
||
<p>| Runtime | Serial ns/op | Parallel ns/op | Ratio vs native (serial) | Ratio vs native (parallel) | |---|---:|---:|---:|---:| | <strong>native</strong> | <strong>1,197</strong> | <strong>694</strong> | 1.0× | 1.0× | | pyvm (CPython 3.13) | 4,089 | 2,765 | 3.4× | 4.0× | | goja | 4,513 | 1,652 | 3.8× | 2.4× | | wazero (AssemblyScript) | 9,956 | 3,271 | 8.3× | 4.7× | | v8go | 11,895 | 12,667 | 9.9× | <strong>18.3× (degrades)</strong> |</p>
|
||
<h3>Cold start (per <code>Load()</code>)</h3>
|
||
<p>| Runtime | ns/op | Ratio vs native | |---|---:|---:| | native | 16,847 | 1.0× | | goja | 78,282 | 4.6× | | v8go | 906,033 | 53.8× | | <strong>wazero (AS)</strong> | <strong>3,936,863</strong> | <strong>233.7× (JIT compile)</strong> |</p>
|
||
<h3>Per-invocation memory</h3>
|
||
<p>| Runtime | B/invoke | allocs/invoke | |---|---:|---:| | <strong>pyvm (CPython 3.13)</strong> | <strong>496</strong> | <strong>10</strong> (LOWEST allocs of any non-native) | | v8go | 673 | low | | native | 1,450 | minimal | | goja | 3,433 | JS → Go marshalling | | wazero (AS) | 44,425 | JSON ptr/len + linear-memory copy |</p>
|
||
<h3>Binary size delta</h3>
|
||
<p>| Runtime added | Binary growth | |---|---:| | native (registry only) | +89 KB | | wazero | +620 KB | | goja | +10.7 MB | | v8go | +36.3 MB (cgo + V8 statics) |</p>
|
||
<h3>Scale findings (added 2026-05-19 after the second benchmark pass)</h3>
|
||
<p>The throughput benchmark above measured a single hot module. The scale benchmark measured fan-out — many modules, many tenants, many concurrent invocations — and <strong>materially changes the recommendation for two runtimes</strong>.</p>
|
||
<p><strong>Per-loaded-module Go-heap cost (steady state, 1000 modules loaded):</strong></p>
|
||
<p>| Runtime | Per-module heap | Total at N=1000 | Total at N=10000 | |---|---:|---:|---:| | native | ~16 B | <1 MB | ~1 MB | | goja | ~9 KB | ~9 MB | ~90 MB | | wazero (pool=8) | ~635 KB | ~635 MB | (extrapolated 6.4 GB) | | wazero (pool=4) | ~320 KB | ~320 MB | (extrapolated 3.2 GB) | | v8go | crashed before reaching N=500 (SIGSEGV in libv8) |</p>
|
||
<p><strong>Sustained concurrent invocations on one module (throughput at M concurrent):</strong></p>
|
||
<p>| Runtime | M=10 ops/s | M=100 ops/s | M=1000 ops/s | M=10000 ops/s | |---|---:|---:|---:|---:| | native | scales linearly with M | linear | linear | linear | | goja | scales | scales | <strong>188,000</strong> | scales | | wazero (pool=4) | scales | scales | pool exhaustion above pool size; queueing | queueing | | v8go | OK at M=10 | <strong>SIGSEGV in libv8</strong> | (process crash) | (process crash) |</p>
|
||
<p><strong>Pool-size sweep (1000 tenants, wazero):</strong></p>
|
||
<p>| Pool size | Latency | Memory | |---:|---:|---:| | 1 | high (queueing) | ~80 MB | | 4 | <strong>good</strong> | <strong>~320 MB</strong> | | 16 | same as 4 | ~1.3 GB | | 64 | same as 4 | ~5.1 GB | | 256 | same as 4 | <strong>10.8 GB</strong> |</p>
|
||
<p>No latency improvement beyond pool=4. Anything higher is pure waste.</p>
|
||
<p><strong>Concrete corrections this forces:</strong></p>
|
||
<ol><li><strong>v8go is removed from the production decision tree.</strong> v8go v0.9 on</li></ol>
|
||
<p> darwin/arm64 SIGSEGVs inside libv8 at ~100 concurrent invocations on a shared isolate. This is not "slow" — it is <strong>process death</strong>. Production-disqualifier for any service expecting real concurrency. <code>plugins/v8vm</code> ships but is for benchmarking and experimental use only. Tracked upstream — revisit if v8go ships per-context isolation and resolves the crash.</p>
|
||
<ol><li><strong>goja is the production winner for multi-tenant JS at scale.</strong></li></ol>
|
||
<p> ~9 KB per loaded module, 188K ops/s on a single module at M=1000 concurrent, no cgo, no crash modes. For a SaaS deployment hosting thousands of tenants each with a few JS extensions, goja is the right call. The cooperative-interrupt caveat remains, but the stability-at-scale story dwarfs it.</p>
|
||
<ol><li><strong>wazero default pool is 4, not 8.</strong> No throughput gain beyond that</li></ol>
|
||
<p> for the workloads measured; halving the pool halves the per-module memory floor.</p>
|
||
<ol><li><strong>wazero scales to ~10K modules at pool=4 (~3.2 GB).</strong> Beyond that,</li></ol>
|
||
<p> compile-cache miss + linear-memory floor compounds; see Open Questions below for a future test.</p>
|
||
<ol><li><strong>native scales to any reasonable N.</strong> ~16 B per loaded function</li></ol>
|
||
<p> pointer; the goroutine cost (~8 KB) dominates only at >100K concurrent invocations of any single module.</p>
|
||
<p>Full numbers and methodology in <code>~/work/hanzo/base/docs/EXTENSIONS_BENCHMARK.md</code> under "## Scale Study".</p>
|
||
<h2>The new standard</h2>
|
||
<p><strong>Go-native is the default.</strong> Every metric in the benchmark — serial perf, parallel scaling, cold start, memory, binary size — favors native by a factor of 2-50×. There is <strong>no scenario in this benchmark where any other runtime beats native on raw performance.</strong> If the code is Hanzo-authored and the language constraint allows Go, write it in Go.</p>
|
||
<p><strong>Pick another runtime only when one of these four exceptional conditions holds:</strong></p>
|
||
<h3>How a host loads extensions</h3>
|
||
<p><code>Loader.LoadDir(ctx, dir)</code> scans <code>dir</code> for subdirectories holding an <code>extension.json</code>, resolves each manifest's <code>runtime</code> against the runtimes linked into the binary, and returns the loaded modules by name. A manifest naming a runtime the binary does not carry is logged and skipped, not fatal — which is what lets one binary serve hosts built with different runtime sets.</p>
|
||
<p>That is the whole loading contract. WHERE a host points it — a hooks directory, a per-service directory, a path from config — is the host's decision and belongs to HIP-0106, not here. This HIP specifies what a runtime is and how a module is loaded; it does not name directories on anyone's disk.</p>
|
||
<p>A host that exposes extensions to more than one tenant is responsible for admitting only runtimes whose isolation it accepts. pyvm and v8vm share process memory and have no hard sandbox.</p>
|
||
<h3>Decision tree</h3>
|
||
<ol><li><strong>Is the code Hanzo-authored and Go-permissible?</strong> → <strong>native</strong>.</li></ol>
|
||
<p> Default; no further questions.</p>
|
||
<ol><li>**Is the code user-supplied AND threat model requires HARD sandbox</li></ol>
|
||
<p> (e.g. tenants could be actively malicious)?**</p>
|
||
<ul><li><strong>Language flexibility matters?</strong> (Rust / TinyGo / Zig / AssemblyScript /</li></ul>
|
||
<p> C plugin authors) → <strong>wazero</strong>. Pool default 4.</p>
|
||
<ul><li><strong>JS authoring only?</strong> → wazero with Javy (once the WASI-stdio shim</li></ul>
|
||
<p> lands — see Open Questions). Until then, accept the soft sandbox and use goja (see next item).</p>
|
||
<ol><li>**Is the code user-supplied JS where the threat model is "ordinary</li></ol>
|
||
<p> customers, not adversaries"?<strong> → </strong>goja**. Per the scale findings, this is the right answer for multi-tenant SaaS hosting thousands of JS extensions — ~9 KB per loaded module, 188K ops/s at high concurrency, no crash modes, no cgo. The cooperative-interrupt caveat applies; pair with a <code>ctx</code> deadline and resource limits at the host boundary.</p>
|
||
<ol><li>**Is the code an existing <code>.base.js</code> hook from the legacy <code>plugins/jsvm</code></li></ol>
|
||
<p> path?<strong> → </strong>goja** (back-compat).</p>
|
||
<ol><li><strong>Are you tempted to use v8go for "modern JS perf"?</strong> → **Don't, for</li></ol>
|
||
<p> production.** v8go v0.9 SIGSEGVs inside libv8 at modest concurrency (~100 invokers). The <code>plugins/v8vm</code> runtime ships but is for benchmarking and experimental use only until upstream ships per-context isolation that resolves the crash.</p>
|
||
<ol><li>**Do you need REAL CPython (with the full ecosystem including</li></ol>
|
||
<p> numpy, pandas, cryptography) inside the Go binary, and is your deployment SINGLE-TENANT?<strong> → </strong>pyvm**. CPython 3.13 embedded via a small direct cgo bridge: <code>plugins/pyvm/pyvm_bridge.{c,h}</code> includes <code><Python.h></code> and calls <code>Py_InitializeEx(0)</code>, leaving signal handling to Go. There is no intermediate binding library. The bridge consolidates a whole invocation into one cgo call (<code>pyvm_invoke</code>), which is the point: per-call cgo crossings, not CPython, dominate the JSON-pipe embedding contract.</p>
|
||
<p> Beats wazero AS by ~2× serial and has the lowest per-invocation memory (496 B/op) of any sandboxed runtime measured. Sub-interpreter pool gives per-tenant-style isolation within the single-process deployment.</p>
|
||
<p> <strong>DO NOT use pyvm in multi-tenant builds.</strong> A C extension segfault in any tenant's code kills the entire host process and every other tenant. Multi-tenant operators must policy-reject <code>runtime: pyvm</code> in extension manifests. Gate with <code>-tags pyvm</code> at build time; default off.</p>
|
||
<p> Python 3.13 free-threading (PEP 703, <code>python3.13t</code>) is detected at runtime via <code>pyvm.GilDisabled()</code>; when present, the GIL is a no-op and OWN_GIL sub-interpreters become unnecessary for parallelism. <strong>Measured 2026-05-18 on Apple M1 Max, default <code>BASE_PYVM_POOL_SIZE=4</code>: free-threading is a non-event for pyvm's embedding workload.</strong></p>
|
||
<p> | Build | Serial ns/op | Parallel ns/op | |---|---:|---:| | 3.13 default-GIL | 4,073 | 5,733 | | 3.13t free-threaded | 4,478 | 5,805 |</p>
|
||
<p> PEP 684 OWN_GIL sub-interpreters already deliver per-OS-thread parallelism on default-GIL; PEP 703 doesn't add headroom unless you abandon the sub-interp pool and run many threads against one interpreter — which we don't. The pool size is the lever, not the GIL mode. Revisit when CPython 3.14+ ships free-threading as default with closed serial-perf gap. Full measurement: <code>~/work/hanzo/base/docs/EXTENSIONS_BENCHMARK.md</code>.</p>
|
||
<ol><li>**Are you serving a workload where seconds of cold start is fine and</li></ol>
|
||
<p> GPU is needed?** → That's HIP-0060 Functions, not this. Wrong HIP.</p>
|
||
<h3>What we are NOT recommending</h3>
|
||
<ul><li><strong>Don't use v8go for hot-path parallel workloads.</strong> The single-isolate</li></ul>
|
||
<p> mutex in v8go v0.9 serializes everything; parallel scaling is worse than serial. We hit this in the benchmark and have no workaround until v8go ships per-context isolation (upstream issue tracked).</p>
|
||
<ul><li><strong>Don't use wazero for latency-sensitive code that is loaded per-request.</strong></li></ul>
|
||
<p> 234× native coldstart eats your tail latency budget. Pre-load at boot and reuse modules.</p>
|
||
<ul><li>**Don't rewrite working Go code to wasm under the assumption that</li></ul>
|
||
<p> "wasm is faster".<strong> It is 4-10× slower in this benchmark for equivalent CPU-bound work. Wasm wins on </strong>sandbox**, not speed.</p>
|
||
<ul><li><strong>Don't put Hanzo-internal service logic behind any non-native runtime.</strong></li></ul>
|
||
<p> Per HIP-0014 every Hanzo service ships as a single Go binary. Service logic is native code; extension points are where user code lives.</p>
|
||
<h3>Honest caveats baked into the recommendation</h3>
|
||
<ul><li>The goja interrupt is <strong>cooperative</strong>. A malicious extension author can</li></ul>
|
||
<p> write a tight numeric loop with no function-call opcodes and resist <code>ctx.Done()</code>. If your threat model requires hard abort, use wazero or v8go. (<code>SupportsAbort: true</code> for goja is honest in the common case; caveated against adversarial guests.)</p>
|
||
<ul><li>Wazero <code>module.Close()</code> for hard-abort <strong>destroys the instance permanently</strong>.</li></ul>
|
||
<p> The Hanzo wazero runtime auto-refills the pool from a background ctx to keep pool size stable. Memory pressure from refills under sustained cancellation is something to watch in observability.</p>
|
||
<ul><li>V8go's <code>TerminateExecution</code> is <strong>isolate-wide</strong>. Because Hanzo serializes</li></ul>
|
||
<p> on the isolate today, the cancellation target is unambiguous. If/when v8go grows per-context isolation, the cancellation story has to be re-examined.</p>
|
||
<h2>Reference implementation</h2>
|
||
<ul><li><strong>Packages</strong> (<code>hanzoai/base</code>, on <code>main</code>):</li><li><code>plugins/extruntime/</code> — interface, manifest, native impl, loader</li><li><code>plugins/gojavm/</code> — goja adapter</li><li><code>plugins/wasmvm/</code> — wazero (pure Go)</li><li><code>plugins/pyvm/</code> — CPython via <code>pyvm_bridge.{c,h}</code> (cgo)</li><li><code>plugins/starkvm/</code> — Starlark</li><li><code>plugins/v8vm/</code> — v8go (cgo, <code>-tags v8vm</code>, stub for the default build)</li><li><code>plugins/extbench/</code> — fixtures + benchmark harness</li><li><strong>Tests</strong>, on the default build: extruntime 6 passed, gojavm 7 passed,</li></ul>
|
||
<p> wasmvm 2 passed and 4 skipped, v8vm 0 — its tests are behind <code>//go:build v8vm</code>, so the default build compiles the stub and runs nothing.</p>
|
||
<ul><li><strong>Verification</strong>: <code>go build ./plugins/...</code> and <code>go test ./plugins/...</code></li></ul>
|
||
<p> are clean. The <code>v8vm</code> tag is NOT verified: <code>rogchap.com/v8go v0.9.0</code> is declared in <code>go.mod</code> but absent from the module cache, so a tagged build cannot reach the compiler without fetching it.</p>
|
||
<h2>Backwards compatibility</h2>
|
||
<p>The existing <code>plugins/jsvm</code> API (goja-based hooks for <code>.base.js</code> files) is <strong>untouched</strong>. Old hooks continue to work via the old path. The new extension runtime is <strong>additive</strong> — opt in by writing an <code>extension.json</code>.</p>
|
||
<h2>Security considerations</h2>
|
||
<ul><li><strong>Sandbox boundary</strong> is the runtime's responsibility. wazero and v8go</li></ul>
|
||
<p> enforce memory isolation; goja and native share the host heap.</p>
|
||
<ul><li><strong>Resource limits</strong>: wazero supports stack limits and memory caps;</li></ul>
|
||
<p> v8go v0.9 lacks a per-isolate heap-limit API (V8 default ~768MB-1.5GB applies). Host code MUST set a <code>ctx</code> deadline on every Invoke to protect against runaway CPU.</p>
|
||
<ul><li><strong>Path traversal</strong>: the loader resolves <code>module</code> relative to the</li></ul>
|
||
<p> manifest directory and refuses paths containing <code>..</code>.</p>
|
||
<ul><li><strong>Manifest validation</strong>: <code>name</code> must be alphanumeric + dash/underscore;</li></ul>
|
||
<p> <code>runtime</code> must be one of the four known values; an unknown runtime causes the extension to be skipped with a logged warning, not loaded against the wrong engine.</p>
|
||
<h2>Open questions</h2>
|
||
<ol><li><strong>Javy support</strong> — Shopify's Javy (raw JS → wasm via QuickJS-in-wasm)</li></ol>
|
||
<p> emits a WASI command module (<code>_start</code> reads stdin, writes stdout). Our wazero convention is pointer-based. The two ABIs don't compose without a stdio shim. Either we ship the shim (a small wazero adapter that forwards stdio buffers as the pointer-based payload) or we publish a Javy plugin that emits our convention directly. Tracked in <code>plugins/extbench/fixtures/wazero-javy/TODO.md</code>.</p>
|
||
<ol><li><strong>Component Model / WIT</strong> — wazero's component-model branch is</li></ol>
|
||
<p> experimental. Once stable, we should reconsider whether the hand-rolled pointer/len ABI is worth the simplicity or if we should adopt WIT interfaces. Likely revisit Q3 2026.</p>
|
||
<ol><li><strong>Hot reload</strong> — <code>plugins/jsvm</code> has filesystem watching; the new</li></ol>
|
||
<p> extension loader does not. Add only if a real consumer asks for it.</p>
|
||
<ol><li><strong>Host API surface</strong> — what can extension code call back into? DB</li></ol>
|
||
<p> access, HTTP fetch, KMS reads, log emission? Each runtime needs plumbing. Suggest a separate HIP for the host-API contract once we have a concrete extension that exercises it.</p>
|
||
<h2>References</h2>
|
||
<ul><li>Reference implementation: <a href="https://github.com/hanzoai/base/tree/main/plugins">hanzoai/base/plugins</a></li><li>Benchmark writeup: <code>~/work/hanzo/base/docs/EXTENSIONS_BENCHMARK.md</code></li><li>wazero: https://github.com/tetratelabs/wazero</li><li>goja: https://github.com/dop251/goja</li><li>v8go: https://github.com/rogchap/v8go</li><li>AssemblyScript: https://www.assemblyscript.org/</li><li>HIP-0014 (Application Deployment Standard) — service-level binaries</li><li>HIP-0026 (Identity and Access Management Standard) — per-org isolation</li><li>HIP-0060 (Serverless Functions Standard) — K8s-scale FaaS, complementary</li></ul>
|
||
<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-0105.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
|
||
</footer>
|
||
</div></body></html> |