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

268 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-1064</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-1064.md">
<link rel="icon" href="/favicon.svg">
<link rel="canonical" href="https://hanzoskills.com/hip-1064">
</head>
<!-- Reading this with a machine? Every page here is also plain markdown.
This one: https://hanzoskills.com/hip-1064.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-1064</h1><p class="lede">HIP-1064: Flow — The Canvas Plane. Status Final. Hanzo architectural specification.</p><h1>HIP-1064: Flow — The Canvas Plane</h1>
<h2>Abstract</h2>
<p>Hanzo Flow is the visual agent-workflow product — a canvas, a graph engine and a component library — and it lives in its own repository, <code>hanzoai/flow</code>, written in Python. <code>/v1/flow</code> is the cloud&#x27;s endpoint onto it.</p>
<p>This HIP specifies what the endpoint adds and, more importantly, what it refuses to add. The cloud contributes exactly three things: identity, the tenant boundary, and the unified surface. It contributes no data model, because a plane that remodels a product&#x27;s shapes can drift from them. The implementation is <code>hanzoai/cloud</code> <code>apps/flow</code>.</p>
<h2>Motivation</h2>
<p>Two failure modes bracket this kind of endpoint.</p>
<p>The first is reimplementation: cloud grows its own workflow model beside the product&#x27;s, and the two diverge until a graph saved through one cannot be read through the other. The second is the honest-looking document: an address list is authored for the product&#x27;s full intent, published, and answers nothing — measured, an authored spec for this product carried paths that returned a route-level 404 everywhere they were probed. A client cannot tell an unimplemented operation from a broken one.</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 product owns its shapes</h3>
<p>Every operation is a typed passthrough. Responses relay the product&#x27;s own payloads verbatim — a workflow is the product&#x27;s workflow object, a page is its own pagination envelope, a run is its own run response. This plane MUST NOT remodel them, and therefore cannot drift from them.</p>
<p>Typing here describes the envelope and the address, not the product&#x27;s interior. That is the whole point of the relay: the schema this plane publishes is a promise it can keep.</p>
<h3>The tenant boundary is the product&#x27;s own project</h3>
<p>The product runs as a single shared deployment reached with one platform credential, so the org boundary MUST be enforced in the cloud, on a primitive the product already has: each org&#x27;s workflows live in a project named by the org id, resolved server-side per request.</p>
<p>Consequently:</p>
<ul><li>The org comes from the validated principal (HIP-0026) and is never an input</li></ul>
<p> field.</p>
<ul><li>A create pins the project server-side. A caller cannot name one.</li><li>Every per-workflow read or mutation verifies the workflow is in the caller&#x27;s</li></ul>
<p> project and answers 404 otherwise. <strong>A foreign id and an unknown id MUST be indistinguishable</strong>, so existence never leaks.</p>
<ul><li>The project primitive itself gets no route. Exposing it would hand a caller the</li></ul>
<p> address of another org&#x27;s project, which is the one thing the boundary rests on.</p>
<h3>Failure is attributed correctly</h3>
<ul><li>No validated principal: refused before any upstream byte.</li><li>The upstream refusing the platform credential: <strong>503</strong>. That is a deployment</li></ul>
<p> fault, and reporting it as an authorization failure would send the caller to debug their own credentials for a problem they cannot see.</p>
<ul><li>Upstream 5xx: 502. Unreachable upstream: 503.</li></ul>
<p>An empty platform credential is a valid posture for a development deployment and MUST NOT be treated as an error at mount.</p>
<h3>The honest slice</h3>
<p>What is mounted is the subset the product&#x27;s server genuinely answers, each operation proven against a live backend before it shipped. Everything else gets <strong>no route at all</strong> — a smaller true surface rather than a larger fake one — and the refused families are a closed ledger with a reason each (<code>apps/flow/typed_wire_test.go:46</code>), measured against the live router: 404 there, absent from the document.</p>
<p>The reasons fall in two groups, and the distinction is normative because the remedies differ:</p>
<ol><li><strong>Primitives this product does not have.</strong> The authored intent carried a</li></ol>
<p> component model, connection, trigger-queue and key-value vocabulary from a different lineage. Those belong to capabilities that exist elsewhere in the fleet — connectors at <code>/v1/connectors</code> (HIP-1065), triggers and the piece runtime on the automation plane (HIP-1063), keyed storage in its own product. Such a family MUST NOT be revived here; it is already served.</p>
<ol><li><strong>Product surface not yet proven against a real backend.</strong> These may ship, and</li></ol>
<p> shipping one is a deliberate edit to the ledger plus an operation proven against a live server. Never a drive-by.</p>
<p>Every route on this surface is a typed operation and the count of untyped routes is held at zero, so a raw handler added later fails rather than shipping without a schema.</p>
<p>The addresses are the operations at <code>/v1/flow</code> (plugin/flow/openapi.json): workflows (list, create, get, patch, delete), runs (start, list), and the <code>/status</code> reachability lens.</p>
<h3>What it owns, and what a run costs</h3>
<p>The capability owns no store: workflows and runs live in the product&#x27;s own database upstream, and the honest slice reads them back verbatim.</p>
<p>It is metered. The plugin declares <code>Price: cloud.Metered</code> (plugin/flow/main.go:23), and the unit is one <strong>run</strong>. Running a workflow executes its whole component graph upstream, and those components call model providers, so the meter sits on <code>POST /v1/flow/runs</code> and nowhere else — everything else is bookkeeping against rows already held (apps/flow/billing.go). The price per run is the deployment&#x27;s <code>CLOUD_FLOW_FEE_CENTS_RUN</code> (then <code>CLOUD_FLOW_FEE_CENTS</code>, then the platform default <code>cloud.DefaultResourceFeeCents</code>, 100 cents). The gate authorizes exactly the amount the meter debits — one fee read serves both, so the number a caller is refused for and the number they are charged cannot drift — and the debit lands through the resource meter after the upstream returned: work that never ran is work nobody owes for.</p>
<p>It publishes no events on the platform 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.</p>
<p>The stage is <code>ga</code> — the manifest row declares none, and absent is <code>ga</code> (HIP-0139 §8).</p>
<p>The product is a fork: <code>hanzoai/flow</code> derives from Langflow (MIT), rebranded, and the canvas, the graph engine and the component library all survive in HEAD. The cloud side forks none of it — every operation is the typed passthrough this HIP already requires.</p>
<h2>Rationale</h2>
<p>The alternative to a shared deployment with a cloud-side boundary is one deployment per org. It gives isolation by construction and costs a per-org lifecycle, a per-org credential, and idle capacity for every org that has drawn one graph. The project-per-org boundary keeps a single deployment and puts the isolation in tested code paths on the cloud side, where the identity already is.</p>
<h2>Security Considerations</h2>
<p>One shared upstream credential means the upstream cannot distinguish tenants; the endpoint is the only thing that can. Two properties carry it: the project is pinned server-side on write, and every per-workflow operation passes an ownership check whose negative answer is identical to the not-found answer.</p>
<p>The credential itself is delivered from the key store into the process environment and never appears in a response. An upstream rejection of it is reported as a deployment fault precisely so that a misconfigured credential can never be mistaken for a caller-side authorization result.</p>
<h2>References</h2>
<ul><li>HIP-0026 — Identity and Access Management</li><li>HIP-0106 — Hanzo Plugin Contract</li><li>HIP-0119 — Hanzo Service Conventions</li><li>HIP-1063 — Auto — Flows That Run Themselves</li><li>HIP-1065 — Connectors — A User&#x27;s Own Credentials</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-1064.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
</footer>
</div></body></html>