Files
skills/public/hip-1240.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

251 lines
20 KiB
HTML
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<!doctype html>
<html lang="en"><head>
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
<title>hip-1240</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-1240.md">
<link rel="icon" href="/favicon.svg">
<link rel="canonical" href="https://hanzoskills.com/hip-1240">
</head>
<!-- Reading this with a machine? Every page here is also plain markdown.
This one: https://hanzoskills.com/hip-1240.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-1240</h1><p class="lede">HIP-1240: O11y — The Observability Plane. Status Final. Hanzo architectural specification.</p><h1>HIP-1240: O11y — The Observability Plane</h1>
<h2>Abstract</h2>
<p><code>/v1/o11y</code> is your logs, metrics, traces and errors: ship them in, query them, chart them (<code>apps/o11y/o11y.go:1</code>). One subsystem owns the cloud&#x27;s whole observability plane — the tenant-scoped reads, the query engine, the dashboards and alerts, the Sentry-compatible error face, and the public platform status document. The implementation is <code>hanzoai/cloud</code> <code>apps/o11y</code> over the embedded <code>hanzoai/o11y</code> runtime. <code>o11y</code> is a sanctioned abbreviation (HIP-0139 §2.5).</p>
<h2>Motivation</h2>
<p>This plane was five separately registered subsystems whose names leaked five public concepts; they collapsed to one registration of the name <code>o11y</code> (<code>apps/o11y/o11y.go:23-31</code>). The addresses have not finished following: the manifest row still carries three roots outside the capability&#x27;s own (<code>manifest/apps.go:84</code>). This HIP states the surface the name rule settles.</p>
<h2>Specification</h2>
<p>The key words MUST, MUST NOT, SHOULD, SHOULD NOT and MAY are to be interpreted as in RFC 2119.</p>
<h3>The addresses, and the three that fold</h3>
<p>Every route this capability serves MUST be under <code>/v1/o11y</code>. Three families still answer at other roots — <code>/v1/sentinel</code>, <code>/v1/summary</code> and <code>/ws/query_progress</code> (<code>manifest/apps.go:84</code>); each pair is ledgered in cloud&#x27;s <code>openapi/misfiled.txt</code> and closes by fold, never by alias:</p>
<ul><li>The Sentry-compatible face — projects, issues, stats, traces, the reads a</li></ul>
<p> signed-in person makes — moves to <code>/v1/o11y/sentinel/*</code>. It is the SAME runtime under a second path family with no rewrite (<code>apps/o11y/o11y.go:535</code>), so it is one capability&#x27;s second face, not a second capability.</p>
<ul><li>The public status document moves to <code>/v1/o11y/summary</code></li></ul>
<p> (<code>apps/o11y/summary.go:156</code>). It stays unauthenticated — a status read must work when IAM is down and carries no tenant data — and unauthenticated is not un-prefixed.</p>
<ul><li>The websocket progress read moves onto its own HTTP twin: <code>/ws/query_progress</code></li></ul>
<p> is the same read as <code>/v1/o11y/query_progress</code> delivered over an Upgrade (<code>apps/o11y/o11y.go:132,141</code>), so the fold is one address, two protocols.</p>
<p>The beacon endpoint is NOT this capability&#x27;s address: <code>/v1/event</code> belongs to <code>event</code> (HIP-1190), which forwards the Sentry wire through the plane ops to this capability&#x27;s sink (<code>apps/o11y/o11y.go:651</code>, <code>apps/o11y/obs_rpc.go</code>). A minted DSN keeps addressing <code>/v1/event</code> unchanged.</p>
<p>The runtime names every route, and the typed ones carry their prose in their own doc comments. The ones that cannot be values are declared with prose beside the wire fact (<code>apps/o11y/o11y.go</code> init): the live tail and the progress read are a stream and a long poll, with no single value to answer; the raw export answers a file, not JSON; the sign-in callbacks answer a Location header and no body; the DSN ingest paths carry a foreign wire the SDKs own the spelling of; and the sentinel wildcard is a relay whose routes the runtime carries.</p>
<h3>The store</h3>
<p>The capability owns the <code>event.*</code> plane on the shared warehouse — <code>event.event</code>, <code>event.log</code>, <code>event.span</code>, <code>event.metric</code>, <code>event.error</code>, one shared envelope (<code>apps/o11y/LLM.md:437-438</code>) whose DDL the <code>hanzoai/o11y</code> module owns — plus the runtime&#x27;s control-plane metadata in SQLite under cloud&#x27;s data dir (<code>apps/o11y/embed.go:80-96</code>).</p>
<h3>The tenant</h3>
<p>Telemetry is a tenant&#x27;s OWN data, so org membership is the whole admission test (<code>apps/o11y/o11y.go:367</code>): no validated principal is 403; a validated but org-less principal is refused rather than served unscoped; the org is the identity boundary&#x27;s minted claim (HIP-0026), never a header the caller sends. Platform sudo buys the cross-tenant fleet view one level in — it MUST NOT be the product gate, because that would make the only way to see your own errors a scope that shows you everyone&#x27;s. Which operations are exempt is the module&#x27;s own answer (<code>module.Anonymous</code>); the DSN ingest authenticates by publishable key, in constant time, failing closed, and derives the org from the key.</p>
<h3>Price, events, emission, stage</h3>
<p>It is free, in those words: telemetry ingest charges nothing and declares <code>cloud.Free</code> (<code>spend.go:196</code>). It publishes no events on the bus, so a customer&#x27;s webhooks receive nothing from it; alert delivery leaves through the module&#x27;s own alert egress, which reports delivery as delivery, never arrival (<code>apps/o11y/alerts.go</code>). Its own emission is the plane itself: cloud&#x27;s spans land in <code>event.span</code> (<code>apps/o11y/LLM.md:494</code>) and the fleet probes write <code>hanzo_service_up</code> into <code>event.metric</code> every 30 seconds (<code>apps/o11y/probes.go</code>) — the signal <code>/v1/o11y/availability</code> and the summary project. The stage is <code>ga</code>, and the row is Eager (<code>manifest/apps.go:84</code>): a status document read during an outage must not pay a cold start.</p>
<h3>Upstream</h3>
<p>The runtime is <code>hanzoai/o11y</code> v1.5.66 (<code>go.mod:694</code>), forked from SigNoz (MIT Expat, copyright 2020–present SigNoz Inc.), synced to upstream <code>main</code> at <code>3e6339019</code>. What survives in HEAD is the query service, dashboards, alerts, rule manager and sqlstore, constructed in-process by the one builder the standalone binary uses (<code>apps/o11y/embed.go</code>). The Sentry face implements that wire (<code>hanzoai/o11y</code> <code>pkg/modules/sentry/implsentry</code>); it takes no code from Sentry.</p>
<h2>Rationale</h2>
<p>The alternative to the sentinel fold is a split — errors as their own capability. It is refused on the store: both faces read the same runtime over the same <code>event.*</code> plane, and HIP-0139 §7.2 permits a split only along a store boundary. The alternative for the websocket was keeping a transport-named root; folding the Upgrade onto its HTTP twin leaves one address for one read.</p>
<h2>Security Considerations</h2>
<p>The dangerous case is the absent org, not the forged one: the gate reads only server-minted identity headers, and an org-less request is refused rather than served unscoped. The ingest exemption is matched by method plus prefix plus suffix, never a bare prefix, so no read is reachable through it. The status document never answers &quot;operational&quot; from an absence of data — when the availability source cannot be read it answers 503, because a green status page over a blind probe is the one output worse than none (<code>apps/o11y/summary.go</code>).</p>
<h2>References</h2>
<ul><li>HIP-0026 — Identity and Access Management</li><li>HIP-0106 — Hanzo Plugin Contract</li><li>HIP-0135 — What Is Public</li><li>HIP-0139 — Capability</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-1240.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
</footer>
</div></body></html>