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

264 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-1220</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-1220.md">
<link rel="icon" href="/favicon.svg">
<link rel="canonical" href="https://hanzoskills.com/hip-1220">
</head>
<!-- Reading this with a machine? Every page here is also plain markdown.
This one: https://hanzoskills.com/hip-1220.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-1220</h1><p class="lede">HIP-1220: Commerce — The Merchant Half. Status Final. Hanzo architectural specification.</p><h1>HIP-1220: Commerce — The Merchant Half</h1>
<h2>Abstract</h2>
<p><code>/v1/commerce</code> is selling: checkout, subscriptions, invoices, spend alerts, payment webhooks, the storefront and its catalog, carts, priced SKUs and the typed payment endpoint. It is <code>hanzoai/cloud</code> <code>apps/commerce</code>, which mounts the <code>hanzoai/commerce</code> module natively on the cloud&#x27;s own router — one router, one specificity space, zero handler adaptation (<code>apps/commerce/mount.go:3-14</code>).</p>
<p>This HIP states the target surface — one root for every merchant noun — and the boundary with <code>billing</code>, the customer money endpoint HIP-0018 declares: commerce is the merchant half and the store it owns; billing is the address a customer&#x27;s money questions are answered at.</p>
<h2>Motivation</h2>
<p>The app answers at eight top-level roots today (<code>manifest/apps.go:116</code>), which puts a cart, a storefront and a payment in three different generated client classes for one subsystem. HIP-0139 §7.1&#x27;s default closes that: an app with one store is one capability, however many nouns it answers for.</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 One root</h3>
<p>Every route commerce serves MUST be under <code>/v1/commerce</code>:</p>
<ul><li><code>/v1/commerce/cart</code> — the shopper&#x27;s basket (from <code>/v1/cart</code>; HIP-1220).</li><li><code>/v1/commerce/catalog</code> — the merchant catalog rows in commerce&#x27;s store,</li></ul>
<p> merging the SuperAdmin CRUD now at <code>/v1/catalog/*</code>.</p>
<ul><li><code>/v1/commerce/payments</code> — the typed payment endpoint (from <code>/v1/payments</code>;</li></ul>
<p> HIP-1220).</p>
<ul><li><code>/v1/commerce/plans</code> — plan ROWS in commerce&#x27;s datastore (from</li></ul>
<p> <code>/v1/plans/{entries,seed}</code>). The <code>/v1/plans</code> root is the plans capability&#x27;s; these rows are not that catalog and take commerce&#x27;s prefix.</p>
<ul><li><code>/v1/commerce/store</code> — storefronts, listings, checkout (from <code>/v1/store</code>;</li></ul>
<p> HIP-1220).</p>
<ul><li>the tenant-admin surface, from <code>/_/commerce</code> — HIP-0139 §3.3, nothing outside</li></ul>
<p> <code>/v1</code>; same audience, same binary. This half of the fold lands in the <code>hanzoai/commerce</code> module, which registers those routes (one module release).</p>
<p>Where the router still serves the old spellings, the pairs are the <code>commerce</code> lines in cloud&#x27;s <code>openapi/misfiled.txt</code>, and each closes by fold, never alias.</p>
<h3>§2 The billing boundary</h3>
<p>Commerce MUST NOT serve <code>/v1/billing</code>. That address is billing&#x27;s (HIP-0018), answered over the plane; commerce keeps the store and publishes the plane operations — balance, the prepaid gate, credit, usage, transactions, spend and scope rules (<code>apps/commerce/mount.go:204-210</code>) — that the money endpoint and every metered surface debit through. One store, one publisher, one address that is somebody else&#x27;s.</p>
<h3>§3 The store it owns</h3>
<p>Per-tenant merchant and money stores under <code>&lt;DataDir&gt;/commerce</code> (<code>apps/commerce/mount.go:319-323</code>), encrypted under the process master key when the sqlcipher codec is linked. The at-rest posture is decided in exactly one function (<code>apps/commerce/mount.go:161-170</code>): a production build refuses to open money data unencrypted, and a pure-Go dev build gets the module&#x27;s documented unencrypted dev store rather than no money plane at all.</p>
<p>The customer ledger of record is NOT here: <code>EmbedConfig.Ledger</code> injects <code>apps/finance</code>, so a credit minted by a settled charge lands in the one ledger (<code>apps/commerce/mount.go:6-8</code>).</p>
<h3>§4 Tenant</h3>
<p>The paying org is read from the validated principal (HIP-0026) and never from a request field — a field is caller-supplied, and an org read from one is a cross-tenant write the caller asserted for itself (<code>apps/commerce/payments.go:25-30</code>). A card payment taken here can only credit the caller&#x27;s own org.</p>
<h3>§5 Price, and the screen on the mint</h3>
<p>The surface is free, in those words: <code>Price: cloud.Free</code> (<code>plugin/commerce/main.go:21</code>) — it is the path to payment itself. The meter downstream of the edge is the one §2 publishes.</p>
<p>Both endpoints that mint spendable balance from a settled charge — the browser top-up and the typed payment op — MUST wrap their handler, not their route, with the one risk screen (<code>apps/commerce/mount.go</code>, the credit-screen note; <code>apps/commerce/risk.go</code>): a typed op is projected four ways and only the handler is the point all four run through.</p>
<h3>§6 Events and observability</h3>
<p>No <code>commerce.&lt;noun&gt;.&lt;verb&gt;</code> events reach the platform bus, so a customer&#x27;s webhooks (HIP-1310) receive nothing from it directly. A settled charge is stated once, as the analytics event <code>order_completed</code> through the same capture core <code>POST /v1/event</code> reaches (<code>apps/commerce/emit.go:24-31</code>, <code>:58</code>, <code>:80</code>) — counted by the same lenses, forwarded by the same destinations fan-out. The emit is detached and bounded: a conversion row is expendable, a settled payment is not. Beyond the request span every route gets, it emits nothing.</p>
<h3>§7 Typed and declared</h3>
<p>The operations this repo owns are typed: payments, invoices, cart, the health probe and the plane ops. The embedded module&#x27;s surface is declared with prose beside the live route (<code>apps/commerce/describe.go:3-14</code>), which cannot add an operation, only explain one that exists. Each declared route is a typing the module still owes — the honest typed op exports a value-taking core from the module first — not a route that can never be typed (<code>apps/commerce/mount.go</code>, the module-handler note).</p>
<h3>§8 Stage and upstream</h3>
<p>The stage is <code>ga</code> — the manifest row declares none, and absent is <code>ga</code> (HIP-0139 §8).</p>
<p>It derives from <code>hanzoai/commerce</code> (pinned v1.50.58 in cloud&#x27;s <code>go.mod:18</code>), dual-licensed MIT / Apache-2.0. The whole module survives in HEAD — routes, datastore, middleware — embedded in-process. PAN-touching paths relay to the out-of-process Payments/Vault; this binary holds tokens and intent ids only and is not in PCI-DSS scope (<code>apps/commerce/mount.go:16-19</code>).</p>
<h2>Rationale</h2>
<p>The alternative to the fold is a split into cart, store, payments and catalog capabilities. All of them read and write commerce&#x27;s one datastore, so the split is four apps on one store — the defect HIP-0139 §7.2 refuses by name. The nouns stay; they become path segments of the app that owns their rows.</p>
<h2>Security Considerations</h2>
<p>The wrong implementation hands an attacker the mint. A screen mounted on the router instead of the handler leaves the same authorized deposit reachable unscreened through the tool projection; an org taken from a request field turns a card payment into a cross-tenant credit; a per-config at-rest posture lets a production build quietly write plaintext money data where the per-build decision in §3 refuses to boot.</p>
<h2>References</h2>
<ul><li>HIP-0018 — Payment Processing Standard</li><li>HIP-0026 — Identity and Access Management</li><li>HIP-0106 — Hanzo Plugin Contract</li><li>HIP-1220 — Cart · HIP-1220 — Payments · HIP-1220 — Store</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-1220.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
</footer>
</div></body></html>