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

252 lines
21 KiB
HTML

<!doctype html>
<html lang="en"><head>
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
<title>hip-1312</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-1312.md">
<link rel="icon" href="/favicon.svg">
<link rel="canonical" href="https://hanzoskills.com/hip-1312">
</head>
<!-- Reading this with a machine? Every page here is also plain markdown.
This one: https://hanzoskills.com/hip-1312.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-1312</h1><p class="lede">HIP-1312: Company — The Formation Machine. Status Final. Hanzo architectural specification.</p><h1>HIP-1312: Company — The Formation Machine</h1>
<h2>Abstract</h2>
<p><code>/v1/company</code> brings a legal entity into existence and records who owns it: choose a structure, add founders, clear identity, pay the formation fee, generate documents, route signature, anchor the equity genesis. The implementation is <code>hanzoai/cloud</code> <code>apps/company</code>.</p>
<p>The capability is a <strong>guarded state machine</strong> — a closed table of stages and the edges between them (<code>apps/company/machine.go</code>) — plus provider seams that reach the outside world (<code>apps/company/providers.go</code>). HIP-0903 argues why a firm should run this way; this is the contract the surface answers to.</p>
<h2>Motivation</h2>
<p>Formation is a sequence where every step depends on a fact an earlier one established, and most of those facts are legal rather than technical: money must not move before identity clears, and an entity must not be reported as formed before it is.</p>
<p>Enumerating what a caller may do — a permission list — fails in the direction that matters here. A list has gaps, and a gap is a company incorporated without a verified person behind it. A closed edge table has none: the illegal move is not forbidden, it is absent.</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 machine</h3>
<p>Two paths reach the terminal stage, every edge carrying a guard (<code>apps/company/machine.go</code>): <strong>incorporate</strong> — <code>structure → founders → payment → documents → esign → genesis → company</code>, guarded by structure chosen, identity verified, fee paid, documents generated, signature complete, genesis recorded; and <strong>import</strong> — <code>structure → import → company</code>, for an entity that already exists and brings its own cap table and documents.</p>
<p>The table MUST stay closed: an edge that is not listed does not exist, so no request shape, argument or ordering advances a formation past a guard. A new step is a new edge with a new guard in the table, never a condition in a handler.</p>
<h3>§2 The addresses</h3>
<p>Twenty-one paths, every one under <code>/v1/company</code> (<code>manifest/apps.go:433</code>, <code>plugin/company/openapi.json</code>): the machine&#x27;s edges (<code>/structure</code>, <code>/founders</code>, <code>/kyc</code>, <code>/kyc/decision</code>, <code>/kyc/refresh</code>, <code>/payment</code>, <code>/documents</code>, <code>/esign</code>, <code>/esign/complete</code>, <code>/genesis</code>, <code>/advance</code>, <code>/skip</code>), the import pair, the fundraise trio, the platform book (<code>/register</code>, <code>/register/summary</code>, <code>/review</code>) and the <code>GET|POST /v1/company</code> root.</p>
<p>Twenty operations are typed. Two are declared with prose beside the route and held to that count by a test (<code>apps/company/typed_wire_test.go</code>): the deck upload takes a PDF as the raw request body, which has no value to name, and <code>POST /payment</code> answers denial with the fleet&#x27;s nested error body, which a typed operation cannot emit. Both declare their bodies through <code>openapi.Register</code>, so neither publishes an address nobody can explain.</p>
<h3>§3 The store, and the tenant</h3>
<p>One SQLite file in the system namespace — <code>company</code> — holds each org&#x27;s formation as a single row keyed by the org, at most one formation per org (<code>apps/company/store.go:22-28</code>). Documents, cap-table rows and signing material are NOT here: they live with <code>dataroom</code>, <code>captable</code> and <code>kms</code> behind the provider seams (<code>apps/company/providers.go</code>), and a formation row that also held them would make this capability the second owner of three other stores.</p>
<p>The org is <code>principal.Org</code>, the validated IAM owner claim (HIP-0026), on every read and write; a caller with no validated principal is refused.</p>
<p>Two surfaces are SuperAdmin&#x27;s and cross-tenant by nature: the platform book (<code>/register</code>, <code>/register/summary</code>, <code>/review</code>) and the identity decision (<code>/kyc/decision</code>). Hanzo forms the entity, so Hanzo carries the formation identity obligation, and discharging it is the platform&#x27;s own act rather than a predicate over the customer&#x27;s. The two planes MUST stay orthogonal — the SuperAdmin operation writes a fact, the machine&#x27;s guard reads it, neither calls the other — and a reviewer&#x27;s confirmation MUST be recorded as its own distinct value, never as a provider verification. &quot;A human confirmed this&quot; and &quot;a provider verified this&quot; stay different facts to an auditor forever. Every privileged decision carries the deciding reviewer.</p>
<h3>§4 The genesis anchor</h3>
<p>The founding allocation — entity plus founders, ordered deterministically — is hashed to a keccak root and committed to the Hanzo L1 (chain <code>36963</code>) by a KMS-signed transaction (<code>apps/company/genesis.go</code>). The chain is the source of truth, so a holder of the allocation recomputes the root without trusting this platform. When the RPC or the signer is unconfigured, the root MUST be returned with an honest <code>pending</code> status: a transaction hash is never fabricated and formation is never blocked on an unreachable chain.</p>
<h3>§5 Price, events, emission, stage, upstream</h3>
<p>The capability is <strong>metered</strong>: <code>Price: cloud.Metered</code> (<code>plugin/company/main.go:27</code>; <code>spend.go:294</code>) — the surface moves a four-figure sum, so the edge requires standing. The one charge is the one-time formation fee — 99900 cents (<code>formationFeeCents</code>, <code>apps/company/providers.go:146</code>; operator override <code>CLOUD_COMPANY_FEE_CENTS</code>, <code>apps/company/company.go:290-297</code>) — taken at <code>POST /v1/company/payment</code> through the charge seam onto the org&#x27;s own ledger. Insufficient balance is 402 and an unreachable balance is 503; neither advances the stage, because the paid guard reads the receipt rather than the attempt (<code>apps/company/machine.go:332-335</code>).</p>
<p>It publishes no events on the bus, so a customer&#x27;s webhooks (HIP-1310) receive nothing from it — provider completion arrives INBOUND at <code>/esign/complete</code> and <code>/kyc/decision</code>, it is not emitted. It emits nothing to observability beyond the request span every route gets.</p>
<p>The stage is <code>beta</code> (HIP-0139 §8): a vertical application rather than core, so an org reaches it by the <code>company</code> flag. The manifest row declares it (<code>manifest/apps.go:433</code>, <code>Stage: Beta</code>). It derives from no OSS upstream — the identity and filing providers are hand-written clients behind the seams (<code>apps/company/providers.go</code>, <code>apps/company/filing.go</code>).</p>
<h2>Rationale</h2>
<p>The alternative to the closed edge table is scopes: enumerate what each caller may invoke and check the enumeration in every handler. It costs one gap to be wrong, the gaps are invisible until exploited, and each new stage multiplies the checks that must agree. The table has one place to be right.</p>
<p>The alternative to the platform book is per-tenant records only, which cannot answer what the obligation actually poses: how many formations await review, and which have waited longest. That question is cross-tenant because the duty is.</p>
<h2>Security Considerations</h2>
<p>The wrong implementation hands an attacker one of three things. Another org&#x27;s formation row is its founders&#x27; identity documents and personal data — the most sensitive record this platform holds outside secrets. A decision operation reachable by a non-SuperAdmin is laundered identity approval: a self-declared founder who then clears the guard. And an edge table with one extra entry is a company formed without payment or without a verified person behind it — a real entity, in a real jurisdiction, traceable to us. The anchor adds a fourth: a fabricated transaction hash is a false claim of public verifiability, worse than no claim, because a reader who checks the chain and finds nothing has already relied on it.</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-0903 — The Agentic Company — Autonomous Firms on Hanzo</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-1312.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
</footer>
</div></body></html>