Files
skills/public/hip-1328.html

290 lines
23 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-1328</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-1328.md">
<link rel="icon" href="/favicon.svg">
<link rel="canonical" href="https://hanzoskills.com/hip-1328">
</head>
<!-- Reading this with a machine? Every page here is also plain markdown.
This one: https://hanzoskills.com/hip-1328.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-1328</h1><p class="lede">HIP-1328: Forge — The Meta Code Host. Status Draft. Hanzo architectural specification.</p><h1>HIP-1328: Forge — The Meta Code Host</h1>
<h2>Abstract</h2>
<p>Forge is where software is built: the tools, the CI/CD and the repository in one place. This HIP proposes that it stop being a place code <em>lives</em> and become the place code is <em>reached from</em>. A repository stays on whichever host its owner already uses — GitHub, GitLab, a Gitea, or any git endpoint we hold credentials for — and Forge connects to it, caches what it needs to run a build, indexes it for search, and synchronises issues, boards and projects in both directions. A durable copy of the objects is kept only when someone pays for one.</p>
<p>The name follows the shape: the current service hosts repositories (HIP-1232); the proposed service federates hosts. <code>/v1/code</code> (HIP-1114) is the search surface this makes cross-platform, and the GitOps plane (HIP-1122) is what runs against a repository Forge does not own.</p>
<p>Nothing here is shipped. Cloud serves no <code>/v1/forge</code> and holds no <code>forge</code> row in its manifest — repositories answer at <code>/v1/git</code> today (HIP-1232) — so this HIP declares no <code>capability:</code> in front matter. It claims the name when the prefix is served, and not before; a Draft that reserves a capability slot makes the coverage gate report a spec for a surface a caller cannot call.</p>
<h2>Motivation</h2>
<p>Two observations, one economic and one operational.</p>
<p><strong>Nobody wants a fourth place to put their code.</strong> A team that uses GitHub uses GitHub. Asking them to migrate, or to accept a mirror as the real copy, is the cost of adoption and it is a cost we do not need to charge. What a team does want is one place that can see across the hosts they already use: search that answers over all of them at once, CI/CD that runs regardless of which one the repository sits on, and an issue tracker that does not force a choice.</p>
<p><strong>Holding copies is the expensive part, and it is the part that breaks.</strong> Measured on the running forge, 2026-09-08:</p>
<p>| Fact | Value | |---|---| | Repositories held | 385 | | Object storage on disk | 26.3 GB (<code>/data/git</code>) | | Mirror set the reconciler targets | ~1,400 repositories | | Postgres crash-recovery before it accepted connections | ~11 minutes (fsync of the data directory) |</p>
<p>During that recovery the forge answered <code>424 Failed Dependency</code> on <code>/v1/healthz</code>, never became Ready, and the edge returned <code>503 no available server</code>. The repository <em>data</em> was never at risk — but availability was, and the recovery time is a function of how much we hold. Every repository we copy adds storage, adds recovery time, and adds a second copy that can disagree with the first.</p>
<p>The mirror set exists so that CI can build from it and search can index it. Neither requires a durable copy. A build requires the objects at one commit for the duration of the build; an index requires content, not custody.</p>
<h2>Current behavior</h2>
<p>Stated as fact, from the implementation:</p>
<ul><li><code>apps/git</code> serves <code>/v1/git</code>: bare repositories on disk, smart-HTTP and SSH,</li></ul>
<p> imports, pull-mirrors and browse pages (HIP-1232). The copy is authoritative for anything native, and a mirror otherwise.</p>
<ul><li><code>hanzoai/mirrors</code> reconciles every qualifying GitHub repository into a</li></ul>
<p> pull-mirror on the forge, on a six-hour schedule.</p>
<ul><li><code>/v1/code</code> (HIP-1114) searches an org&#x27;s repositories with hybrid retrieval —</li></ul>
<p> lexical, symbolic and semantic, fused by reciprocal rank. Its corpus is the repositories the forge holds.</p>
<ul><li>Push-to-deploy has no inbound webhook: a push into the embedded server fires</li></ul>
<p> the builder in-process, and a GitHub-homed repository&#x27;s events arrive through the Hanzo Platform GitHub App.</p>
<p>So the corpus of both CI and search is exactly &quot;what we copied&quot;. This HIP changes what defines the corpus, not how either engine works.</p>
<h2>Specification</h2>
<h3>1. A connected host is the unit</h3>
<p>A <strong>connection</strong> binds an external host to an org: a kind (<code>github</code>, <code>gitlab</code>, <code>gitea</code>, <code>git</code>), an endpoint, and a credential held in KMS. <code>github</code>, <code>gitlab</code> and <code>gitea</code> connections use the host&#x27;s own app/integration so that repository- and org-level configuration can be read and written, not merely cloned. The <code>git</code> kind is the fallback: any endpoint reachable with a credential, tracked and cached, with no platform features beyond the objects themselves.</p>
<p>A <strong>tracked repository</strong> is a repository on a connection that this org has asked Forge to watch. Tracking grants Forge the right to fetch, cache, index and build it. Tracking does not create a copy anyone else can push to, and does not make Forge the source of truth for it.</p>
<h3>2. Cache, not copy — and the paid boundary</h3>
<p>Forge keeps a <strong>cache</strong>: git objects fetched to satisfy a build, an index pass or a browse, retained under an eviction policy and reconstructible at any time from the connection. A cache entry may be dropped without loss.</p>
<p>Forge keeps a <strong>durable copy</strong> only when an org explicitly asks for one and pays for it. A durable copy is what today&#x27;s mirrors are: retained, backed up, and counted against storage. It is the exception, declared per repository.</p>
<p>The free path is therefore proxy and cache; the paid path is custody. This is the inversion the rest of the design follows from, and it is what keeps recovery time bounded by working set rather than by history.</p>
<h3>3. CI/CD against a repository we do not own</h3>
<p>A build takes a connection, a repository and a commit, fetches the objects it needs into the cache, and runs. The existing GitOps plane (HIP-1122) is unchanged — what changes is that its input may be a repository on any connected host.</p>
<p>Events arrive through the connection&#x27;s own integration: the GitHub App for <code>github</code>, the equivalent app for <code>gitlab</code> and <code>gitea</code>, and polling for a bare <code>git</code> connection that has no event channel. Forge does not ask a host to deliver to it by a mechanism the host does not already offer.</p>
<h3>4. Issues, boards and projects, both directions</h3>
<p>For connections whose host has an issue model, Forge synchronises issues, boards and projects bidirectionally, so a team can work in Forge or in their own host without either becoming a stale mirror of the other. The synchroniser is idempotent per item and carries an origin marker so an echo of its own write is not re-applied. Where two sides edit the same field between passes, the rule is last-writer-wins per field with the conflict recorded, not silently dropped.</p>
<p>This is the half that makes &quot;use your favourite host&quot; true rather than aspirational: without it, adopting Forge still costs a team its tracker.</p>
<h3>5. Federated search</h3>
<p>Search answers over three corpora at once:</p>
<ol><li><strong>Tracked content</strong> — indexed by the existing <code>/v1/code</code> tiers (HIP-1114).</li><li><strong>Live host search</strong> — the connected hosts&#x27; own search APIs, queried in real</li></ol>
<p> time and fused with the local result, so a repository that is connected but not yet indexed is still answerable.</p>
<ol><li><strong>Public OSS</strong> — a public index across the three platforms and the package</li></ol>
<p> registries whose source they publish, so a search can reach code the org does not own at all.</p>
<p>Fusion is reciprocal-rank, as <code>/v1/code</code> already does across its tiers; a live host result is one more ranked list, not a special case. A host that is slow or down degrades the result set, never the request.</p>
<h3>6. Surface</h3>
<p>Forge would answer under <code>/v1/forge</code>, one capability, one prefix (HIP-0139), and that prefix is unclaimed today — the front matter takes it on the commit that serves it. <code>/v1/code</code> remains the search surface and gains the federated corpus. <code>/v1/git</code> remains what it is for repositories Forge does host — the paid, durable case, and our own.</p>
<h2>Assumptions</h2>
<ul><li>Every host we federate offers an API sufficient to read repository and org</li></ul>
<p> configuration and to write issues. Verified for GitHub; <strong>not yet verified for GitLab or Gitea</strong> — that check is the first implementation task.</p>
<ul><li>A cache miss is acceptable latency for a build. Not measured; the working</li></ul>
<p> assumption is that a shallow fetch at a known commit is fast enough, and it must be measured before the mirror set is retired.</p>
<ul><li>Public OSS indexing is subject to each platform&#x27;s terms and rate limits. The</li></ul>
<p> scope and legality of a public cross-platform index is an open question, not a settled one.</p>
<h2>Implementation</h2>
<p>Ordered so each step is useful alone:</p>
<ol><li>Connections and credentials: the model, KMS storage, and the <code>github</code> kind</li></ol>
<p> against the existing Hanzo Platform GitHub App.</p>
<ol><li>Tracking and the cache, with builds reading from the cache instead of a</li></ol>
<p> mirror. At this point the mirror set is redundant for CI.</p>
<ol><li><code>gitlab</code> and <code>gitea</code> connections, after their APIs are verified.</li><li>Federated search: live host search fused into <code>/v1/code</code>.</li><li>Issue, board and project synchronisation.</li><li>The paid durable-copy declaration, and retiring mirrors that nobody declared.</li></ol>
<p>Step 2 is the one that changes the operational picture; steps 3–5 are what make the product the user-facing claim.</p>
<h2>Limitations</h2>
<ul><li>Forge stops being able to answer for a repository when the connection&#x27;s</li></ul>
<p> credential is revoked or the host is unreachable. A durable copy is the only thing that survives that, which is precisely what the paid tier sells.</p>
<ul><li>Bidirectional synchronisation cannot make two models identical. Fields one host</li></ul>
<p> has and another does not are carried as metadata or dropped; the mapping is per-host and lossy by construction.</p>
<ul><li>A cross-platform public index is bounded by rate limits and terms, so &quot;all</li></ul>
<p> public OSS&quot; is a direction, not a guarantee.</p>
<ul><li>This HIP does not specify the eviction policy, the conflict-record format, or</li></ul>
<p> the pricing of custody. Each needs its own decision.</p>
<h2>Next step</h2>
<p>Verify the GitLab and Gitea APIs against assumption one, then implement steps 1 and 2. Until a build demonstrably runs from cache at a commit on a connected host that Forge holds no copy of, the rest of this document is a proposal.</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-1328.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
</footer>
</div></body></html>