Files
skills/public/hip-1140.html
zeekayandHanzo Dev 9e10c1c10e Each llms index points at the other two
hanzoskills.com/llms.txt now opens with the install line, the API
reference index and the company index, so an agent that lands on any
one of the three can find the rest.

robots.txt claimed 537 documents while llms.txt counts 920. The number
is gone from robots.txt; llms.txt derives it.

public/ is regenerated from scripts/site.py, which it had fallen
behind: the copy-prompt menu and agent bar were in the generator and
not in the committed pages. tests/site.mjs passes against the result.

Co-authored-by: Hanzo Dev <[email protected]>
2026-09-11 00:27:59 -07:00

260 lines
19 KiB
HTML

<!doctype html>
<html lang="en"><head>
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
<title>hip-1140</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-1140.md">
<link rel="icon" href="/favicon.svg">
<link rel="canonical" href="https://hanzoskills.com/hip-1140">
</head>
<!-- Reading this with a machine? Every page here is also plain markdown.
This one: https://hanzoskills.com/hip-1140.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-1140</h1><p class="lede">HIP-1140: ML — Model Serving. Status Final. Hanzo architectural specification.</p><h1>HIP-1140: ML — Model Serving</h1>
<h2>Abstract</h2>
<p><code>/v1/ml</code> is model serving: deploy a model behind an endpoint and call it. The implementation, <code>hanzoai/cloud</code> <code>apps/ml</code>, is a thin tenant-scoped bridge that turns one KServe CustomResource — <code>InferenceService</code>, <code>serving.kserve.io/v1beta1</code> — into a small REST surface plus one inference proxy. No ML logic is reimplemented: KServe owns reconciliation, and this layer owns exactly two things, the REST↔Kubernetes translation and the tenant boundary (<code>apps/ml/ml.go:1-16</code>).</p>
<h2>Motivation</h2>
<p>Serving a model is cluster work — a CR, a namespace, a data-plane address — and every customer who had to be handed <code>kubectl</code> to do it was handed the cluster. The capability exists so a tenant deploys and calls a model through the same identity, billing and document planes as every other <code>/v1</code> surface, while the cluster remains invisible. Training is deliberately NOT here: a <code>/v1/train/*</code> facade over CRDs the cluster never served was deleted rather than shipped degraded (<code>apps/ml/ml.go:18-25</code>); fine-tuning is the <code>hanzoai/ai</code> broker&#x27;s.</p>
<h2>Specification</h2>
<p>The key words MUST, MUST NOT, SHOULD and MAY are to be interpreted as in RFC 2119.</p>
<h3>The store, and there is none</h3>
<p>This capability owns no store. Its state is the cluster&#x27;s: every read and write is a call on a Kubernetes dynamic client, and deleting the subsystem loses nothing but the endpoint. The client authenticates as the dedicated <code>cloud-ml</code> ServiceAccount when <code>HANZO_ML_TOKEN_FILE</code> names a mounted token, failing closed if the named token is unreadable (<code>apps/ml/ml.go:659-681</code>) — the product-API path never inherits ML&#x27;s cluster reach.</p>
<h3>Addresses</h3>
<p>Seven operations under <code>/v1/ml</code>, three typed and four declared with prose beside the route, each declared one for a wire fact a typed op cannot state (<code>apps/ml/ml.go:210-241</code>):</p>
<ul><li><code>GET /v1/ml/models</code>, <code>GET /v1/ml/models/{name}</code>, <code>DELETE /v1/ml/models/{name}</code></li></ul>
<p> — typed ops (<code>apps/ml/typed.go</code>).</p>
<ul><li><code>POST /v1/ml/models</code> — declared: the pre-create balance gate answers 402/503</li></ul>
<p> in band with the fleet&#x27;s nested <code>{&quot;error&quot;:{code,message}}</code> body, which zip renders only flat.</p>
<ul><li><code>PATCH /v1/ml/models/{name}</code> — declared: an RFC 7386 merge patch relayed</li></ul>
<p> verbatim; re-encoding a merge patch changes what it means.</p>
<ul><li><code>POST /v1/ml/models/{name}/predict</code> — declared: a verbatim proxy of the</li></ul>
<p> predictor&#x27;s own status, bytes and Content-Type (KServe v2 inference protocol), read up to a 32 MiB ceiling.</p>
<ul><li><code>GET /v1/ml/health</code> — declared: a real probe that answers 503 CARRYING the</li></ul>
<p> degraded report — k8s reachability, CRD presence, and the serving-runtime count, which is a separate fact because a cluster with the CRD and no runtime accepts a deploy and never schedules it (<code>apps/ml/ml.go:486-543</code>).</p>
<h3>Tenancy</h3>
<p>The tenant is the gateway-minted org narrowed by the validated project, mapped to a per-tenant Kubernetes namespace: <code>ml-&lt;org&gt;</code>, or <code>ml-&lt;org&gt;-&lt;project&gt;</code> for a non-default project. The mapping MUST be injective — org and project are validated against strict DNS-label patterns with no lossy fold (<code>apps/ml/ml.go:564-598</code>) — and the dynamic client is always pinned to the caller&#x27;s namespace, so naming into another tenant&#x27;s resources is unspellable rather than refused. An unvalidated principal is 403 before any mapping; an org-less caller is refused unless SuperAdmin, who lands in the literal <code>ml-admin</code> bucket.</p>
<h3>Money</h3>
<p>Metered (<code>plugin/ml/main.go</code> declares <code>cloud.Metered</code>; <code>ml</code> is in the <code>meteredApps</code> standing list, <code>spend.go:306</code>). One create is gated and debited through the shared <code>cloud.ResourceMeter</code> under the commerce product label <code>compute</code>, not <code>ml</code> (<code>apps/ml/ml.go:145-171</code>): the balance gate runs BEFORE the namespace or CR exists and fails closed, the fee (<code>CLOUD_COMPUTE_FEE_CENTS[_INFERENCESERVICE]</code>, default $1.00) is debited asynchronously on success against the caller&#x27;s own ledger. Ongoing GPU-hour cost reuses the same meter from a runtime usage watcher and is never fabricated here.</p>
<h3>Events and telemetry</h3>
<p>It publishes nothing to the bus, so a customer&#x27;s webhooks receive nothing from it. Beyond the request span every route gets, it emits log lines only — the mount report and per-operation Kubernetes errors with the missing RBAC named (<code>apps/ml/ml.go:636-644</code>).</p>
<h3>Stage</h3>
<p><code>beta</code>: the manifest row (<code>manifest/apps.go:186</code>) declares <code>Stage: Beta</code>, so per HIP-0139 §8 the capability is dropped from the public projection and its prefix answers 404 unless the caller&#x27;s org holds the <code>ml</code> flag.</p>
<h3>Upstream</h3>
<ul><li>KServe (Apache-2.0): the reconciler this capability drives. Nothing of it is</li></ul>
<p> vendored — the app speaks its CR API and its v2 inference wire.</p>
<ul><li><code>k8s.io/client-go</code> and <code>k8s.io/apimachinery</code> (Apache-2.0): the imported</li></ul>
<p> client through which every cluster call goes.</p>
<h2>Rationale</h2>
<p>The alternative to a thin bridge is reimplementing serving — a scheduler, a rollout loop, a data plane. That buys independence from KServe and costs a second reconciler that must agree with the cluster about everything. The bridge keeps one owner per fact: KServe owns the model&#x27;s lifecycle, this layer owns who may name it. Verbatim relays (patch, predict) are kept verbatim for the same reason — a paraphrased predictor error is this layer inventing an answer the model did not give.</p>
<h2>Security Considerations</h2>
<p>The wrong implementation hands out the cluster. Concretely: a lossy org sanitizer folds two orgs onto one namespace and each reads the other&#x27;s models and predictions; a namespace derived from a request field instead of the validated principal lets any caller deploy into, or predict against, a chosen tenant; and a client built on the pod&#x27;s own broad ServiceAccount instead of the <code>cloud-ml</code> token gives every ML bug the product API&#x27;s full cluster reach. The strict-regex injective mapping, the principal-only tenant resolution and the dedicated token are each the closure of one of those, and the balance gate running before resource creation is what keeps an unfunded org from starting GPU work it will never pay for.</p>
<h2>References</h2>
<ul><li>HIP-0026 — Identity and Access Management</li><li>HIP-0106 — The Hanzo Plugin Contract</li><li>HIP-0139 — Capability</li><li>RFC 7386 — JSON Merge Patch</li></ul>
<h2>Copyright</h2>
<p>Released under CC0 1.0 Universal Public Domain Dedication.</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-1140.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
</footer>
</div></body></html>