Files
skills/public/hip-1313.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
20 KiB
HTML

<!doctype html>
<html lang="en"><head>
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
<title>hip-1313</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-1313.md">
<link rel="icon" href="/favicon.svg">
<link rel="canonical" href="https://hanzoskills.com/hip-1313">
</head>
<!-- Reading this with a machine? Every page here is also plain markdown.
This one: https://hanzoskills.com/hip-1313.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-1313</h1><p class="lede">HIP-1313: Usage — The Metered Record. Status Final. Hanzo architectural specification.</p><h1>HIP-1313: Usage — The Metered Record</h1>
<h2>Abstract</h2>
<p><code>/v1/usage</code> is the categorized read over what an org has spent and consumed, and the write path for the samples a linked provider account contributes. The implementation is <code>hanzoai/cloud</code> <code>apps/usage</code>.</p>
<p>A metered act writes in two places, neither of them here: the money lands on the org&#x27;s commerce ledger and the per-request detail lands in the <code>hanzo.cloud_usage</code> warehouse ledger the ai plane writes (HIP-0106). This capability owns one series of its own — <code>hanzo.account_usage</code>, what the collector posts — and everything else it answers is a read over ledgers other capabilities own.</p>
<h2>Motivation</h2>
<p>&quot;What did this cost me&quot; is asked of three different records: the prepaid balance that was drawn down, the inference detail that explains the draw, and the provider accounts an org linked itself. Answering it from any one of them is wrong — the balance knows the money but not the model, the warehouse knows the model but not the invoice, the linked accounts know neither.</p>
<p>Answering it by copying all three into a fourth store is worse. A copy is a second number that can disagree with the ledger it came from, in the one place a customer will notice and dispute. So this capability composes rather than copies, and the composition is the specification.</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>§1 The addresses</h3>
<p>Every route is under <code>/v1/usage</code> (<code>manifest/apps.go:271</code>, package doc <code>apps/usage/usage.go</code>), all typed, none declared:</p>
<ul><li><code>POST /v1/usage</code> — record account-usage samples, the collector&#x27;s write path</li></ul>
<p> onto the <code>hanzo.account_usage</code> series</p>
<ul><li><code>GET /v1/usage/samples</code> — one provider account&#x27;s own lane, as a time series</li><li><code>GET /v1/usage/summary</code> — the org&#x27;s footprint roll-up, §3</li><li><code>GET /v1/usage/analytics</code> and <code>GET /v1/usage/analytics/access</code> — the</li></ul>
<p> entitlement-gated per-org read, and whether the caller holds the entitlement</p>
<p>Liveness is the host&#x27;s generic <code>GET /v1/usage/health</code>, not one of these: the plugin does not declare <code>OwnsHealth</code>, so the host&#x27;s route stands on a path none of the five shadows.</p>
<p>Per-model and time-series detail is NOT served here — that is <code>/v1/event/*</code> — and the wallet&#x27;s own raw drain is billing&#x27;s <code>/v1/billing/usage</code>. Three addresses answer three questions, and a fourth spelling of any of them would be a fourth number to reconcile.</p>
<h3>§2 What a metered act records</h3>
<p>The recorder&#x27;s wire type is deliberately narrow: subject, namespace, an EXACT decimal USD rather than a rounded cent, currency, model and provider (<code>hanzoai/cloud</code> <code>ai.go:23-30</code>). It carries no prompt content and no PII, and the per-request detail — tokens, latency, per-model breakdown — is the warehouse&#x27;s, not this record&#x27;s.</p>
<p>It carries no idempotency ref, and that absence is load-bearing: the ref this struct once held was derived from client-posted fields, which handed the ledger&#x27;s dedup key to the payer. A future ref MUST be minted server-side or not exist.</p>
<p>The debit itself is not this capability&#x27;s. It lands through the metering client HIP-0106 specifies — authorize before the handler, record after — onto the balance <code>commerce</code> owns. This surface reads that ledger; it never writes it.</p>
<h3>§3 The rollup</h3>
<p><code>GET /v1/usage/summary</code> composes three sources: spend by category off the commerce ledger, LLM totals off <code>hanzo.cloud_usage</code>, and the linked-account board off the series in §4.</p>
<p>Each source MUST degrade independently to honest zeros, with a marker saying which sources answered. A roll-up that hides a dead source behind a plausible total is the worst failure this surface has, because the number still looks like money and a customer will act on it. A zero that says it is a zero is a fact; an unmarked one is a lie with a decimal point.</p>
<h3>§4 Tenant, store, price, emission, stage, upstream</h3>
<p>The tenant is the validated principal, fail-closed: no principal is 401 (HIP-0026). The commerce subject is pinned server-side to that org and every warehouse query binds the org positionally rather than by interpolation, so there is no request shape that widens the scope of a read.</p>
<p>It owns one store: the <code>hanzo.account_usage</code> series (<code>apps/usage/datastore.go</code>), which is what the collector&#x27;s write path fills. Everything else it answers is a read over ledgers other capabilities own, reached over the plane.</p>
<p>Reading it is free, in those words: <code>Price: cloud.Free</code> (<code>plugin/usage/main.go:21</code>) — a lens over spend must not itself spend. It publishes no events on the bus, so a customer&#x27;s webhooks (HIP-1310) receive nothing from it, and it emits nothing to observability beyond the request span every route gets. The stage is <code>ga</code> — the manifest row declares none, and absent is <code>ga</code> (HIP-0139 §8). It derives from no OSS upstream.</p>
<h3>§5 The leaderboard boundary</h3>
<p><code>leaderboard</code> is its own capability with its own specification (HIP-1242) and its own store — the opt-in rows. It is not a view this capability serves.</p>
<p>Today its three routes still answer under <code>/v1/usage/*</code>, which is the one <code>usage</code> line in cloud&#x27;s <code>openapi/misfiled.txt</code>; it closes by leaderboard moving to <code>/v1/leaderboard</code>, never by alias, and <code>/v1/usage</code> is unchanged by the move. The two stay two because the store boundary already exists: leaderboard owns the opt-in rows and reads a derived pre-aggregation of <code>hanzo.cloud_usage</code>, which is the warehouse&#x27;s, not this capability&#x27;s series.</p>
<h2>Rationale</h2>
<p>The alternative is a usage store: materialize every debit and every request row here and serve reads from it. It makes the reads trivial and introduces the one defect this surface cannot carry — a number that disagrees with the ledger a customer is charged against. Composition costs the fan-out in §3 and keeps the ledgers single-owner.</p>
<p>The alternative to marking degraded sources is a single total. It is friendlier in the console and unfalsifiable in support, because nothing in the response distinguishes &quot;you spent nothing&quot; from &quot;the warehouse was unreachable&quot;.</p>
<h2>Security Considerations</h2>
<p>The wrong implementation hands an attacker another org&#x27;s spend and activity profile — which models, how much, when — from a single unbound query. That is commercially sensitive on its own and an operational map of the tenant besides.</p>
<p>The boundary is therefore not a filter applied to results but a bind applied to every statement: the org is never an input a caller supplies, the commerce subject is derived server-side, and each warehouse query carries the org positionally. A read that composes three sources has three places to get that wrong, which is exactly why the rule is stated once and applies to all three.</p>
<p>The record&#x27;s narrowness is the other control. Prompt content never enters this plane, so no breadth of read here discloses what a customer asked a model.</p>
<h2>References</h2>
<ul><li>HIP-0026 — Identity and Access Management</li><li>HIP-0106 — Hanzo Plugin Contract</li><li>HIP-0139 — Capability</li><li>HIP-1242 — Leaderboard — Who Uses AI Most</li><li>HIP-1310 — Webhooks — Outbound Delivery</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-1313.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
</footer>
</div></body></html>