mirror of
https://github.com/hanzoai/skills.git
synced 2026-11-19 00:47:36 +00:00
367 lines
28 KiB
HTML
367 lines
28 KiB
HTML
<!doctype html>
|
||
<html lang="en"><head>
|
||
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
|
||
<title>hip-0108</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-0108.md">
|
||
|
||
<link rel="icon" href="/favicon.svg">
|
||
<link rel="canonical" href="https://hanzoskills.com/hip-0108">
|
||
</head>
|
||
<!-- Reading this with a machine? Every page here is also plain markdown.
|
||
This one: https://hanzoskills.com/hip-0108.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-0108</h1><p class="lede">HIP-108: On-Demand Subsystem Supervisor + Warm Pool. Status Final. Hanzo architectural specification.</p><h1>HIP-0108: On-Demand Subsystem Supervisor + Warm Pool</h1>
|
||
<h2>Abstract</h2>
|
||
<p>This HIP defines how the unified <code>cloud</code> binary (HIP-0106) supervises two things at runtime:</p>
|
||
<ol><li><strong>Out-of-process subsystems</strong> that cannot fold into the Go binary —</li></ol>
|
||
<p> Rust, Python, C++, and TypeScript services with native deps, native sandboxes, or licence/scope constraints that exclude them from the single-binary mount path.</p>
|
||
<ol><li><strong>Per-tenant in-process state</strong> that should not be permanently</li></ol>
|
||
<p> resident — extension modules, sub-interpreters, per-tenant SQLite handles that activate on first request and idle out when traffic stops.</p>
|
||
<p>The contract is <strong>on-demand activation + warm pools + idle eviction</strong>. A realistic Hanzo deployment fits in <strong>1-2 GB RAM at idle</strong> and scales by tenant load rather than by service count.</p>
|
||
<p>This HIP sits on top of HIP-0105 (the in-process runtime substrate), HIP-0106 (the unified binary), HIP-0107 (the replication substrate), and HIP-0302 (per-tenant SQLite + encryption). It introduces one new package — <code>cloud.Supervisor</code> — and one new operator concept: <strong>tiered activation</strong>.</p>
|
||
<h2>Motivation</h2>
|
||
<p>Per the HIP-0106 audit, the unified Go binary itself is ~150 MB resident at idle. But the full Hanzo ecosystem has 13+ out-of-process services that intentionally stay out of the unified binary:</p>
|
||
<p>| Reason out-of-process | Services | |---|---| | Native deps (torch, faiss, sentence-transformers) | flow, llm | | PCI scope isolation (HIP-0106 §Solo-vault CDE) | vault, payments | | Heavy column store with its own replication | datastore | | Free-threading blockers per the 2026-05-19 FT audit | cli, erp, insights, sentry, studio | | Independent frontend / studio process | platform, chat | | Polyglot agent runtimes | brain, agents, bot |</p>
|
||
<p>If all 13 ran "always on, production-sized," the deployment would consume 64-256 GB RAM regardless of actual tenant traffic. Most tenants never touch most services.</p>
|
||
<p><strong>Real workload profile</strong> (Hanzo flagship target):</p>
|
||
<p>| Quantity | What | |---:|---| | 1000 | Total tenants | | ~10 | Concurrently active on ML inference (flow, llm) | | ~50 | Concurrently active on JS extensions (per-tenant goja modules) | | ~100 | Concurrently active on CRUD (per-tenant Base) | | ~840 | Idle in any given minute |</p>
|
||
<p>The "always-on" architecture over-provisions by roughly an order of magnitude. This HIP closes that gap with a supervisor pattern that co-exists with the always-on path for the workloads that warrant it.</p>
|
||
<h2>Specification</h2>
|
||
<h3>Three activation tiers</h3>
|
||
<p>Every workload in a Hanzo deployment falls into exactly one tier. The tier dictates how memory is amortised and how cold-start cost is paid.</p>
|
||
<p>| Tier | What runs there | RSS per active tenant | Cold-start cost | |---:|---|---:|---:| | 0 — in-process | wazero modules, goja runtimes, starlark threads, native Go handlers | 9 KB (goja) – 200 KB (wazero) | sub-millisecond | | 1 — sub-interpreter | per-tenant CPython sub-interp (pyvm), per-tenant Node <code>worker_thread</code> | 2–20 MB | low-millisecond | | 2 — subprocess (warm pool) | per-(tenant, service) supervised OS process; idle-evictable; CRIU-snapshottable on Linux | 50–500 MB active; 0 idle | ~50–100 ms snapshot restore; ~2–10 s cold spawn |</p>
|
||
<p>Tier 0 is the HIP-0105 substrate. Tier 1 sub-interpreters share a process with the unified binary (pyvm pool, Node <code>worker_threads</code>). Tier 2 is what HIP-0108 introduces: <strong>supervised, idle-evictable OS processes scoped per (orgID, service)</strong>.</p>
|
||
<h3><code>cloud.Supervisor</code> API</h3>
|
||
<pre><code class="lang-go">package cloud
|
||
|
||
// Supervisor manages tier-2 warm-pool workers. Workers are OS
|
||
// processes scoped per (orgID, service). The supervisor handles spawn,
|
||
// affinity, idle eviction, optional CRIU snapshots, and resource
|
||
// isolation. Callers receive opaque WorkerHandles.
|
||
type Supervisor interface {
|
||
// Acquire returns a handle to a warm worker for (orgID, service).
|
||
// Blocks until a worker is available (warm from pool or freshly
|
||
// spawned). Caller MUST Release the handle when done.
|
||
Acquire(ctx context.Context, orgID, service string) (WorkerHandle, error)
|
||
|
||
// Stats returns current pool stats for o11y / debugging.
|
||
Stats() SupervisorStats
|
||
}
|
||
|
||
type WorkerHandle interface {
|
||
// Invoke sends a request to the worker over its IPC channel
|
||
// (unix socket / shared memory / ZAP RPC).
|
||
Invoke(ctx context.Context, method string, payload []byte) ([]byte, error)
|
||
|
||
// Release returns the worker to the warm pool (if pool has slack)
|
||
// or schedules it for idle reaping.
|
||
Release()
|
||
}
|
||
|
||
type SupervisorStats struct {
|
||
PerService map[string]ServiceStats
|
||
TotalRSS uint64
|
||
}
|
||
|
||
type ServiceStats struct {
|
||
WarmWorkers int
|
||
ActiveInvokes int
|
||
SnapshotsOnDisk int
|
||
LastEvictionAt time.Time
|
||
}</code></pre>
|
||
<p>The interface is intentionally narrow. Three calls — <code>Acquire</code>, <code>Invoke</code>, <code>Release</code> — cover the lifecycle. The supervisor is the only component that knows whether a request was served by a warm worker, a freshly spawned worker, or a CRIU-restored worker. Callers see a uniform <code>WorkerHandle</code>.</p>
|
||
<h3>Worker lifecycle</h3>
|
||
<ol><li><strong>Cold spawn</strong>. <code>fork</code>+<code>exec</code> the target binary with</li></ol>
|
||
<p> <code>--worker --tenant=<orgID></code> and the ZAP socket fd inherited. The worker performs language-specific initialisation and signals <code>READY</code> over the socket.</p>
|
||
<ol><li><strong>Warm pool</strong>. When <code>Release</code> is called, the worker stays resident</li></ol>
|
||
<p> for <code>idle_timeout</code> seconds (default 60s, configurable per service). Subsequent <code>Acquire</code> calls for the same <code>(orgID, service)</code> return the same worker via consistent hashing.</p>
|
||
<ol><li><strong>CRIU snapshot</strong> (Linux only, opt-in). On idle eviction the</li></ol>
|
||
<p> supervisor may freeze the worker to disk under <code>{data-dir}/snapshots/{org}/{service}.crium</code>. Next <code>Acquire</code> restores in ~50–100 ms instead of a full 2–10 s spawn.</p>
|
||
<ol><li><strong>Idle eviction</strong>. Idle longer than the configured timeout →</li></ol>
|
||
<p> <code>SIGTERM</code> → 5 s grace → <code>SIGKILL</code>. Worker MUST honour <code>SIGTERM</code> gracefully: flush state, release WAL, close fds. The supervisor's ZAP healthcheck verifies the worker handed back its WAL handle before reaping.</p>
|
||
<ol><li><strong>Affinity</strong>. Same tenant routes to the same warm worker via</li></ol>
|
||
<p> consistent hashing on <code>orgID</code>. This is what makes per-tenant in-process state caching effective at tier 2 — the worker's heap already has that tenant's hot rows in memory.</p>
|
||
<h3>Resource isolation</h3>
|
||
<p>Each tier-2 worker runs under explicit limits:</p>
|
||
<ul><li><strong>cgroups v2</strong> per worker process: <code>memory.max</code>, <code>cpu.max</code>,</li></ul>
|
||
<p> <code>pids.max</code>. Limits are per-service defaults overridable per-tenant via supervisor config.</p>
|
||
<ul><li><strong>Namespaces</strong> per worker where the service warrants it: PID,</li></ul>
|
||
<p> network, mount. Network namespace is the common case (the worker reaches outbound services only through the supervisor-provided socket).</p>
|
||
<ul><li><strong>File-descriptor limits</strong> per worker via <code>RLIMIT_NOFILE</code>.</li><li><strong>Graceful shutdown contract</strong>. Worker MUST honour <code>SIGTERM</code>:</li></ul>
|
||
<p> flush in-flight writes, release WAL, close fds, exit within 5 s. Workers that miss the deadline take <code>SIGKILL</code>; their per-tenant SQLite WAL is recovered on next acquire (the SQLite WAL recovery protocol is idempotent — see HIP-0302).</p>
|
||
<h3>Per-tenant WAL handoff (per HIP-0302)</h3>
|
||
<p>When the supervisor activates a warm worker for tenant <code>T</code> against service <code>S</code>:</p>
|
||
<ol><li>The worker receives the file descriptor for</li></ol>
|
||
<p> <code>{data-dir}/orgs/{T}/{S}.db</code>.</p>
|
||
<ol><li>The per-org DEK is fetched from KMS (HKDF-derived from the</li></ol>
|
||
<p> per-service master key per HIP-0302).</p>
|
||
<ol><li>The worker opens SQLite in WAL mode.</li><li>On <code>Release</code> the worker <code>fsync</code>s the WAL and returns control to</li></ol>
|
||
<p> the supervisor.</p>
|
||
<ol><li>HIP-0107 <code>replicate</code> continues streaming WAL changes to</li></ol>
|
||
<p> <code>vfs</code>/S3 regardless of which worker currently holds the handle.</p>
|
||
<p>The consequence: <strong>per-tenant state is shared between the cloud binary AND the warm worker</strong> via the same SQLite file. The cloud binary can read from the same DB while the worker is active — no IPC round-trip for reads from the supervised path. The worker owns WAL writes for the duration of its acquire; the cloud binary defers WAL writes to the worker via the same Supervisor.</p>
|
||
<h3>Service classification</h3>
|
||
<p>For each Hanzo service, the canonical tier and pool size:</p>
|
||
<p>| Service | Activation tier | Pool size | Idle timeout | |---|---|---:|---:| | Most extensions (wazero / goja) | 0 in-process | per-runtime defaults (HIP-0105) | n/a | | <code>pyvm</code> (single-tenant CPython) | 0 in-process | 4 sub-interps | n/a | | <code>flow</code> (visual ML pipeline) | 2 subprocess | 0–2 warm | 120 s | | <code>llm</code> (Python LLM gateway) | 2 subprocess | 1–4 warm | 300 s | | <code>insights</code> | 2 subprocess | 0–1 warm | 60 s | | <code>brain</code>, <code>agents</code> (TS runtimes) | 2 subprocess | 0–2 warm | 60 s | | <code>platform</code> (Next.js UI) | always-on | 1–3 replicas | n/a | | <code>chat</code> (TS UI) | always-on | 1–2 replicas | n/a | | <code>datastore</code> (OLAP column store) | always-on (server) | single | n/a | | <code>vault</code>, <code>payments</code> (PCI scope) | always-on | 2 replicas | n/a |</p>
|
||
<p>The cloud binary's <code>Supervisor</code> manages tier-2 workers only. Tier 0 lives in the HIP-0105 substrate. Always-on services are out of HIP-0108 scope — they remain traditional K8s deployments because either (a) PCI scope dictates isolation, (b) the workload is itself the always-on serving plane (UIs, OLAP), or (c) the service has its own internal idle-management.</p>
|
||
<h3>CRIU integration</h3>
|
||
<p>CRIU lets the supervisor freeze a worker process to disk on idle eviction and restore it on next acquire. The trade-off:</p>
|
||
<ul><li><strong>Snapshot size</strong>: ~100 MB per <code>(orgID, service)</code> snapshot,</li></ul>
|
||
<p> evictable on an LRU policy.</p>
|
||
<ul><li><strong>Restore latency</strong>: ~50–100 ms vs ~2–10 s for a full spawn.</li><li><strong>Platform</strong>: Linux only. macOS dev environments take the</li></ul>
|
||
<p> spawn-only path (no snapshot, no resource limits — see Open Questions).</p>
|
||
<ul><li><strong>Storage</strong>: <code>{data-dir}/snapshots/{org}/{service}.crium</code>. The</li></ul>
|
||
<p> supervisor reuses HIP-0107 <code>vfs</code> semantics for off-host snapshot storage when configured, so snapshots survive node loss.</p>
|
||
<ul><li><strong>WAL replay</strong>: on restore, the worker reopens its per-tenant</li></ul>
|
||
<p> SQLite handle and the HIP-0107 replicate frame stream replays any missed WAL frames before the worker accepts new requests.</p>
|
||
<p>CRIU snapshotting is opt-in per service. The default is spawn-only; operators turn snapshotting on for services where the cold-spawn cost dominates the request budget.</p>
|
||
<h3>Memory budget</h3>
|
||
<p>For the Hanzo flagship profile (1000 tenants; 10 concurrent ML; 50 active JS; 100 concurrent CRUD):</p>
|
||
<p>| Component | RSS | |---|---:| | Cloud baseline (unified binary, all subsystems compiled in) | 150 MB | | Tier 0: in-process extensions (50 active JS × ~9 KB + idle pool overhead) | ~5 MB | | Tier 1: sub-interpreters (4 × ~4.6 MB, shared across tenants via affinity) | ~20 MB | | Tier 2: warm ML workers (10 × ~1 GB) | ~10 GB | | Per-tenant SQLite handles (100 × ~5 MB) | ~500 MB | | Headroom (50%) | ~5 GB | | <strong>Total</strong> | <strong>~16 GB</strong> |</p>
|
||
<p>Compare to ~64–128 GB for an always-on equivalent. The supervisor pattern delivers a <strong>5–10× memory reduction</strong> at the cost of ~50–100 ms restore latency on the cold path (per snapshot) or 2–10 s on a full cold spawn.</p>
|
||
<h2>Implementation phases</h2>
|
||
<h3>Phase 4 — per-service adapters (~1 week each)</h3>
|
||
<ul><li><strong>ML services</strong>: Python via <code>pyvm</code> in supervisor mode (re-using the</li></ul>
|
||
<p> HIP-0105 CPython embed when the workload is single-tenant; spawning full Python subprocess workers otherwise).</p>
|
||
<ul><li><strong>LLM services</strong>: subprocess workers with model weights pre-loaded</li></ul>
|
||
<p> on first acquire and held warm for <code>idle_timeout</code>.</p>
|
||
<ul><li><strong>TS services</strong>: Node <code>worker_threads</code> for lightweight cases; full</li></ul>
|
||
<p> Node subprocess spawn for heavyweight (brain, agents).</p>
|
||
<h2>Non-goals</h2>
|
||
<ul><li><strong>Cluster-level scheduling.</strong> K8s does this. The supervisor is</li></ul>
|
||
<p> in-process to the cloud binary; cross-pod scheduling is not in scope.</p>
|
||
<ul><li><strong>Multi-cluster failover.</strong> HIP scope is per-deployment. The</li></ul>
|
||
<p> supervisor coordinates with HIP-0107 replicate for state durability; multi-cluster failover is a separate concern.</p>
|
||
<ul><li><strong>Hot reload of subsystem code.</strong> Phase 4 may add it for specific</li></ul>
|
||
<p> services, but it is not required by this HIP.</p>
|
||
<ul><li><strong>Folding always-on services into the supervisor.</strong> UIs, OLAP</li></ul>
|
||
<p> stores, and PCI-scoped services stay always-on by design.</p>
|
||
<h2>Open questions</h2>
|
||
<ol><li><strong>macOS dev story.</strong> No CRIU, no cgroups, no namespaces. The</li></ol>
|
||
<p> supervisor MUST work without these on darwin — just no snapshot path and no resource limits. Accept the per-worker memory cost in dev. Linux remains the canonical production target.</p>
|
||
<ol><li><strong>Restart storms.</strong> If a worker crashes mid-request, what is the</li></ol>
|
||
<p> retry semantic? Suggested default: exponential-backoff retry with a circuit breaker — 3 failures in 30 s marks the <code>(orgID, service)</code> unhealthy and short-circuits subsequent acquires for a 60 s cooldown. Surfaced to o11y.</p>
|
||
<ol><li><strong>Tenant migration across clusters.</strong> When tenant <code>T</code> moves</li></ol>
|
||
<p> clusters, what happens to its warm workers and CRIU snapshots? Suggested protocol: "drain on migration signal" — supervisor stops accepting <code>Acquire</code> for <code>T</code>, drains in-flight invokes, reaps the warm worker, leaves snapshot on disk. State on the destination cluster is rebuilt from the HIP-0107 replicate stream on first acquire. CRIU snapshots do NOT migrate; only the replicated SQLite WAL does.</p>
|
||
<ol><li><strong>Backpressure on <code>Acquire</code>.</strong> When the pool is at its max and no</li></ol>
|
||
<p> warm worker is available, <code>Acquire</code> blocks on <code>ctx</code>. Should the supervisor expose a queue depth metric and a per-service <code>max_queue</code> config? Suggest yes — wire under <code>SupervisorStats.PerService[svc].QueueDepth</code> in Phase 1.</p>
|
||
<h2>References</h2>
|
||
<ul><li>HIP-0105 — In-Process Extension Runtime Standard (the substrate</li></ul>
|
||
<p> for tier 0)</p>
|
||
<ul><li>HIP-0106 — Unified Hanzo Cloud Binary (the binary the Supervisor</li></ul>
|
||
<p> lives in)</p>
|
||
<ul><li>HIP-0107 — Streaming Replication over VFS (per-tenant WAL replay</li></ul>
|
||
<p> on worker activation)</p>
|
||
<ul><li>HIP-0302 — Encrypted SQLite + ZapDB Durability (per-tenant SQLite</li></ul>
|
||
<p> + encryption contract the Supervisor honours)</p>
|
||
<ul><li><code>~/work/hanzo/base/docs/EXTENSIONS_BENCHMARK.md</code> — runtime</li></ul>
|
||
<p> perf data underpinning the tier-0/1 numbers</p>
|
||
<ul><li>AWS Lambda warm-starts pattern (architectural inspiration)</li><li>Fly.io <code>fly machines</code> model (single-process supervisor + idle</li></ul>
|
||
<p> suspend)</p>
|
||
<ul><li>Linux CRIU — https://criu.org</li><li>cgroups v2 — kernel docs <code>Documentation/admin-guide/cgroup-v2.rst</code></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-0108.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
|
||
</footer>
|
||
</div></body></html> |