9 Commits

Include renames

Author	SHA1	Message	Date
hanzo-dev	0d602fc9dc	surface: regenerate the document for zip v1.26.0's operation names ... zip v1.26.0 gave an operation ONE naming rule, and the bump landed without re-projecting the document it renames. 758 operationIds across openapi.yaml and 55 plugin subsets still carried the old spellings — post_collaborator_rpc_documentId and v1.admin.affiliates.post_id_approve where the rule now says post_collaborator_rpc_by_documentid and post_v1_admin_affiliates_by_id_approve. Nothing about the surface moved: same paths, same operations, same prose. An operationId is the METHOD NAME in eight generated SDKs, the tool name in the MCP list and the command in the spec-derived CLI, so leaving it stale means every client offers a name the document no longer agrees with. This is what surface-check exists to refuse, and it is why the gate has been red on main: `make describe`, then commit what it wrote. Co-authored-by: Hanzo Dev <dev@hanzo.ai>	2026-08-05 13:40:25 -07:00
hanzo-dev	3b50091c77	mcp: the catalogue is a query — delete the 116 committed tool files ... The fleet's agent door answered from plugin/<app>/mcp.json: the tool array each app's binary projected when it was BUILT, embedded by plugin/embed.go and handed to zip as Plugin.Tools. 116 files, 49,865 lines, and a second source for a fact every child already knows. A second source can only be stale or accidentally correct. This one was stale in the way no gate in this repository could see: o11y's 353 missing ops live in github.com/hanzoai/o11y, so a go.mod bump in ANOTHER repo invalidated an artifact in this one with nothing in the diff to say so. Regenerating it more often is not the fix — a generator on a hook is still two sources with a race between them, and the trigger is in a different repository. (593aa309 did regenerate it, which is why the file reads 365 today. The next cross-repo bump silently un-fixes it.) So the host asks. POST /v1/mcp is the HOST's own handler now (zip's is Disabled, so exactly one handler holds the address). A tools/list forwards the CALLER's own message to every composed subsystem's own /mcp over its private ZAP socket, in parallel, and unions the replies — zip.App.Start resolves a cold child on the same single-flighted path a prefix request takes, so the first list pays one start per app and nothing after it does. A tools/call goes to the app that listed the name, verbatim; the child's own registry decides whether the tool exists. A SUBSYSTEM THAT DOES NOT ANSWER IS NAMED, in result._meta["hanzo.ai/unavailable"], because a silently-short list and a stale file are the same defect: the caller cannot tell an app that serves nothing from one that did not answer. Measured on the built binaries — host + real o11y child, kms pointed at a dead address: tools=364, unavailable=[{kms, connection refused}] 364 and not 365 because o11y projects get_v1_o11y_logs twice; the door serves the first and logs the collision. THAT DUPLICATE IS WHY cmd/cloud's tests were red on main — zip refused the Load ("tool is already served by plugin o11y"), a boot failure. One name still has one owner; it is no longer fatal to the fleet. Also gone with the mechanism they configured: manifest.App.Open and zip's one-open-plugin rule. The host forwards the caller's own request to EVERY subsystem now, so each answers for this caller out of its own rows, and being asked per caller is no longer a privilege one app holds. The release gate moved with the door. Car 3 compared the live tool count against `jq -s length` over the committed files — both sides were the same bytes, so it proved only that the image carried its own tree, and it passed while o11y's catalogue held 12 of 365. It asks the better question now: did every subsystem answer. A broken deployment used to match the files exactly. plugin/<app>/openapi.json SURVIVES, for the one reason the catalogue could not: the weave carries each subsystem's prose, and that prose is lifted from the app's SOURCE at describe time (openapi.Synopsis). A running child has no comment to read and would answer with its deployment's brand blurb, which the weave would publish as the description of every product tag. Deleting that half waits on the synopsis becoming a declared value. Tests are against RUNNING subsystems (fleet/mcp_test.go): real zip children on real ZAP sockets, exact sets, bodies never status codes. Mutation-checked three ways — unmount a child, silence the outage report, ask only the first app — all three go red. Co-authored-by: Hanzo Dev <dev@hanzo.ai>	2026-08-02 14:22:10 -07:00
hanzo-dev	f403c603f1	cloud: the composition root's verb is Listen, because that is what it does ... Serve and Listen were two names for one act. zip's App already calls it Listen — `app.Listen(zapAddr, httpAddr)` — and this function's whole job is to build that app and hand it its addresses, so calling it Serve made the entry point disagree with the thing it enters. One verb, all the way down: a plugin's main says cloud.Listen, cloud says app.Listen, and nothing has to be translated in a reader's head on the way through. 117 composition roots move with it. ServePlane is untouched — it names a different act (bind one app's own socket for the internal plane), and collapsing it into this would be the opposite of the point. Also fixes apps/iam's TestMain, which had gone red on every store test: credz.Boot's last resort is cek.EnsureDevKey, and that DECLINES on a codec-linked build by design — a build that can really encrypt must be handed a real key, not invent one. So the throwaway goes in through the same door a deployment uses, and only when nothing else supplied one. Six failures back to the one pre-existing ratchet (iam serves 97 untyped ops against a budget of 88). Co-authored-by: Hanzo Dev <dev@hanzo.ai>	2026-08-02 09:53:56 -07:00
hanzo-dev	4cfc10d095	docs: the first sentence of a product's doc is the customer's sentence, not ours ... The package doc's opening line is no longer read only by us. openapi/synopsis.go lifts it verbatim into the app's OpenAPI info.description, the weave lands it on the product tag, and from there it is the MCP tool prose an agent reads and the line `hanzo <product> --help` prints. It is the first thing a paying customer sees about a product they are deciding whether to use. Forty of them opened by describing the implementation instead: "mounts the Hanzo Cloud /v1/code/* surface", "folds hanzoai/esign (the Documenso fork) into the unified hanzoai/cloud binary as an in-process subsystem (HIP-0106, task #100, epic #96)". A customer reading the tag list learned our file layout, our epic numbers and our mount order — and not one thing about what they get. Several ran past 200 characters, so the CLI help column truncated mid-clause. So sentence one now answers the only question a buyer is asking: code → search and symbols across your repos, for you and your agents. esign → a document out for signature, signed and filed with an audit trail. world → a live news feed filtered to what your project cares about. NOTHING IS DELETED. Every clause the old opener carried — the mount path, the fork it wraps, the HIP, the tenancy argument — moves down to sentence two, where it is read by the person it was written for. Only the ORDER changed: what the product is, then how it is built. Both were always in the same comment; only one of them projects. The rule the forty now hold, and the reason each is a rule: ≤90 characters (the CLI help column); no "mounts"/"surface"/"subsystem"/"plane"/"binary" (words for where the code lives, not what it does); no /v1 path, file name or HIP number (an identifier no customer can look up); no shouting (the tag list is prose, not a changelog). Sentence two keeps all of it. Two files were already gofmt-dirty on main and are now clean, since they are files this touches: apps/content/doctypes.go (comment alignment) and apps/websearch/websearch.go (list-continuation indent). Regenerated FROM SOURCE, not hand-edited: make describe → 1039 paths, 906 MCP tools. The artifact diff is descriptions only — no path, operation, schema or tool name moves. Co-authored-by: Hanzo Dev <dev@hanzo.ai>	2026-07-30 23:00:51 -07:00
hanzo-dev	c0d7b3f969	openapi: a product tag says what the product is, in its owning package's words ... The document has always known a product's NAME mechanically — the first path segment after /v1/ — and never what the product IS. A caller reading the tag list, an agent reading the MCP door, a CLI printing `hanzo <product> --help` got 144 bare nouns. There is exactly one place that sentence is already written and already reviewed: the package doc of the package that implements the app. So this reads it rather than asking anyone to write it twice. openapi/synopsis.go Synopsis(plugin/<app>) -> the owning package's synopsis. describe.go stamps it into that app's own subset as info.description. openapi/weave.go lifts the tag prose off the subsets it already reads. ONE computation, at the one moment an app describes itself. The weave does not look the mapping up a second time in a second process — it reads the value the app that knows it already wrote down, which is why Weave stays a pure function of its parts. The owner comes from the app's own composition root: plugin/<app>/main.go imports exactly the package it mounts. Nothing else could be the source — four apps are not named after their package (audit->auditlog, evals->eval, plugins->plugin, zero-trust->zt) and one package backs two apps (account, account-bridge), so a name-derived guess is right 107 times and silently wrong 5. An app whose subsystem is another MODULE imports no package here and gets nothing, which is the honest answer. And the comment taken is the one that OPENS "Package …", not go/doc's first-file-in-filename-order fallback. Packages that open their alphabetically-first file with a note about that FILE and state the real package doc in <name>.go would otherwise publish "actions.go — the two GitOps write actions" as the deploy product's description. A misfiled sentence reads exactly like a real one; an absent one does not. 109 of 112 apps have a package doc; 85 of the 144 product tags gain a description. The three without are metrics, authz and licensing, whose subsystem is another module — there is no package here to read. The tag NAME is never conditional on a description: the list stays a function of the document's operations, so nothing enumerating products loses a product because nobody wrote a sentence. The fleet identity remains the fallback for a subset whose package has no doc, and the weave treats a part carrying it as having said nothing. THE LIFTED PROSE LOSES THE HANDLER'S OWN NAME, which is the other half of the same problem. A Go doc comment must open with the identifier it documents, and that identifier is Go's, not the document's: "GetSQL returns one database" reached the OpenAPI description, its summary, the MCP tool description an agent reads, and the CLI help line — naming a function no caller can see. zip drops an exact leading match of the handler's own name from v1.18.13 (main is on v1.18.14, whose lift is byte-identical), and nothing had regenerated against it: 35 packages carried prose the pinned zip can no longer produce. They regenerate here. Three test assertions quoted the leaked identifier and now quote the projection. Every generated artifact is regenerated FROM SOURCE (make -f mk/fleet.mk surface-check, green: 1017 paths). Nothing this commit does moves the wire: of openapi.yaml's 16,439 non-prose leaf facts, 0 changed. The 4 lost and 94 gained are all one thing — surface main already decided and never republished: /v1/insights/e removed and /v1/event given its declared body (6fc2d88c), the six project-scoped git smart-HTTP paths (811ff080), and the sessions' `terminal` property (afdda829). The three bare-root git paths reach no app, so they join router_test.go's unreachable ledger, recorded on the first regeneration that published them. Co-authored-by: Hanzo Dev <dev@hanzo.ai>	2026-07-30 21:33:38 -07:00
hanzo-dev	e247e255cf	mcp: ONE door — three hand-rolled registries collapse into the typed-op projection ... Typing a route bought OpenAPI prose, an SDK method and a CLI command, and NOTHING on the public MCP surface. zip has projected every typed op into an MCP tool since v1.18.6 and cloud never called it: manifest routed /v1/mcp to apps/tools, which hand-rolled its own tools/list + tools/call over a route-table scrape, and apps/automations hand-rolled a THIRD catalogue. Three registries for one concept, and the one the public reached exposed none of the 549 typed ops. THE DOOR IS THE HOST'S. cmd/cloud sets zip.MCPConfig{Path:"/v1/mcp"} and hands each plugin its own catalogue at Load. The host is the only process that CAN own it: MCPTools() is in-process, so a plugin cannot enumerate a lazy sibling, and a plugin-hosted door costs its own wake on the first list. Measured: POST /v1/mcp beats ai's "/v1" remainder by specificity, not registration order. THE LIST IS A BUILD ARTIFACT, so tools/list costs ZERO wakes. It has to be: 112 plugins mount LAZILY, and an MCP client calls tools/list constantly — a door that fanned out over ZAP to ask would destroy the one invariant that makes 112 services affordable. The answer is already fixed at build time, by the same typed-op registry that emits openapi.json, so `<app> describe <dir>` now writes BOTH projections from ONE mount at ONE instant: openapi.json and mcp.json. They cannot be generated apart, so a tool cannot exist without its op or carry a stale schema. The leaf plugin/embed.go go:embeds them (cmd/cloud goes 344 → 345 packages, still zero from apps/). Measured live with the WHOLE fleet mounted: 549 tools listed, child count 4 → 4 (the four eager apps, untouched). tools/call is the ONLY trigger and starts exactly one child — p.target(), the same single-flighted lazy path a prefix request takes — then forwards the SAME message to that plugin's own /mcp over ZAP on its 0700 unix socket. Never HTTP. The child's registry answers, so the host can only NAME a tool, never invoke one the child did not declare. Measured live: get_v1_pricing woke 1 child and returned the pricing catalog; get_v1_company answered its own handler's "X-Org-Id required" through the plugin's full cloud.Serve identity chain. DELETED, not left dark: apps/tools/builtin.go (223 lines) — the "full-cloud-control" route→tool scrape. Structurally dead since the monolith died: in the tools CHILD, GetRoutes() sees only tools' own ~13 routes, and its schemas were opaque {query,body} objects a model cannot fill. The new door is what it meant to be, with real schemas. apps/tools/http.go's mcp/mcpToolList/mcpToolCall/rpcResult/rpcError + the route. apps/automations/mcp.go's mcp/mcpTools/mcpResultObj/mcpErrorObj + its route. GET /v1/mcp — a Source view that is GET /v1/tools?source=mcp by its own comment. Principal.credential + credentialHeaders — replay state only builtin.go read. KEPT, because it is a different capability: apps/tools' EXTERNAL MCP server registry (records, KMS-sealed secrets, SSRF-validated dialer, tools/list fan-out), now owning /v1/mcp/servers alone. Its tools, org skills, agents, functions and connector actions are ROWS, not code, so no build-time catalogue can hold them — they are reached through the typed POST /v1/tools/call, which is itself a tool on the door. Nothing lost: connectorToolProvider already published every connector action into that one registry. THE GATE. mk/fleet.mk surface-check (which .hanzo/workflows/cicd.yml → hanzo.yml app-contract actually invokes) regenerates every app FROM SOURCE and fails on `git status --porcelain -- openapi.yaml plugin/` — mcp.json is under plugin/, so it was covered the moment it landed there. PROVEN TO FIRE: adding one typed op to apps/guide without regenerating turned it red on BOTH plugin/guide/mcp.json and plugin/guide/openapi.json; reverted, green. Four more, all cheap: no App row may claim /v1/mcp (fiber MERGES byte-identical patterns, so a Load there would shadow the door silently); no served path may END in /mcp; no Go source outside cmd/cloud may name an /mcp path unless it is a named foreign engine (apps/tasks' own surface, which is not a projection of our ops); every catalogue tool must be an operationId of its own app, unique fleet-wide, with a NON-EMPTY description — the last one because a nameless tool is a silent failure a model pays context for. 549 tools across 36 apps, 349KB on the wire. zip v1.18.11 → v1.18.12. Capability check, precisely: the 17 executable connector actions the deleted automations door listed are NOT tool names on the fleet door, because they are per-tenant rows — connectorToolProvider publishes every one of them into the ONE registry from the same `registry` map that door read, so they are reached through tools_call with the same activation, price, meter and audit. Nothing is lost; one hop is added. Same for org skills, agents, functions and external MCP servers. One door this gate structurally cannot claim: /v1/tasks/mcp is hanzoai/tasks' own engine surface behind cloud's identity gate, mounted on a raw net/http mux so it is in no subset at all. It is a foreign engine's tools, not a projection of ours, so it is NAMED in foreignDoors with the reason rather than deleted. Co-authored-by: Hanzo Dev <dev@hanzo.ai>	2026-07-30 10:11:38 -07:00
hanzo-dev	16576f8169	type: 27 addresses that published nothing — 19 now describe themselves ... The work list was the ARTIFACT, not a grep: every operation in plugin/{usage,venue,world,agent,bot,help}/openapi.json carrying neither a description nor a summary — exactly the set that projects to nothing at all. No prose, no MCP tool, no CLI command, no typed SDK method. It was 27 of 27. 19 are typed ops now: usage 5/5, venue 5/5, help 4/4, world 4 of 5, bot 1 of 4. Every one carries a doc comment that is TRUE of its handler, and every published schema property carries its own — 0 bare properties across all five subsets. Eight stay untyped and each names its wire fact AT its registration, gated by untypedByDesign + TestEveryRouteIsTypedOrNamed so the two ledgers must sum to what the live router serves: GET /v1/world/stream Server-Sent Events; no Out expresses a stream. GET /v1/bot/connect a WebSocket upgrade; 101 then duplex frames. POST /v1/bot/nodes/{id}/invoke a 403 carrying a DOMAIN body a client switches on, plus the caller's X-Device-Id, which no In field may carry. POST /v1/bot/peer/invoke a net/http machine hop with text/plain refusals and a MaxBytesReader cap. the four /v1/agent ops registered by github.com/hanzoai/agent v0.1.3 (agent.go:166-169), not by cloud. They become typeable upstream, which additionally needs a per-request bridge there; POST /v1/agent also relays an upstream 4xx's status AND body. Two latent defects found by typing and fixed: plugin/venue/main.go declared no Prefixes, so the standalone binary's scope owned only the /v1/<name> default — and venue is named "venue" and serves /v1/cloud, so it owned NOTHING it registers. cloud.Declare attributed every route to no subsystem and scope.Use installed the app's middleware where no route lives, which is load-bearing now that cloud.Bridge parks the org a typed op reads. The apps/plan defect, one app over. apps/bot had no Makefile, so `make -C apps/bot openapi` could not run and that subset could never be regenerated by the per-app chain — despite mk/plugin.mk claiming an app cannot have a main and no Makefile. catalog, crawl, meet and zen are still missing theirs. One delta, MEASURED rather than glossed and not fixable in cloud: encoding/json validates the whole document before invoking any custom Unmarshaler, so the record-it-and-judge-it-later input that preserves gate order for an oversized or wrong-shaped body cannot preserve it for bytes that are not JSON at all — zip refuses those first. TestSyntacticallyInvalidJSONIs400Early (help) and TestSyntaxErrorIs400BeforeTheAdminGate (venue) pin exactly what moved. Wire preserved otherwise, and pinned: the 413-after-404-after-503 intake order, the body-tolerant sync, the ?project cross-check that a body cannot become, the no-store header on the two money reads, the one-or-many usage report, and the tenant that comes from the validated principal in every case. Co-authored-by: Hanzo Dev <dev@hanzo.ai>	2026-07-30 10:01:45 -07:00
antje	85dd3a6513	name: a thing the host loads is a Plugin ... MountSpec was a compound naming a struct after the mechanism that consumes it. The thing it describes is one of the plugins the host loads: name, price, mount. The directory is plugin/, the framework is the zip plugin framework, and every doc comment already called them plugins in prose. So: Plugin. Not App, which was the obvious first choice and is wrong twice over -- package cloud already declares an App in payloads.go, and the struct itself carries an App field for a subsystem that gates the whole binary. Either collision alone would have made the name ambiguous at every use site. Mechanical: 132 files, plus the parameter and loop variables that carried the old noun (specs, spec, sp) to the noun they actually hold.	2026-07-28 16:48:54 -07:00
hanzo-dev	2c4b045b0b	cmd/cloud + plugin/<app>: the light host is the one binary — scope credentials, forward flags, own "/" ... Restructure to the canonical layout: cmd/host → cmd/cloud (the host IS the one real binary; name it cloud), and every other cmd/<app> → plugin/<app>. `ls cmd/` is `cloud/` alone; `ls plugin/` is the 116 per-app + tool dirs. gen-app-cmds scaffolds into plugin/<app> and scans plugin/ for the bijection; the Dockerfile / Makefile / mk / hanzo.yml / weave / controlplane-containment gate all read the new paths. go build ./cmd/cloud links ~399 pkgs and zero subsystems. credz KMS-key leak (#51 follow-up): zip builds each child's env as append(os.Environ(), Plugin.Env...), so a host that keeps CLOUD_KMS_MASTER_KEY_REF hands the root key to EVERY child — the Root posture credz exists to prevent, and now the default entrypoint. cmd/cloud (stdlib credz/launch only — importing credz would drag cek→sqlite and re-fatten the host) mints the launch secret, scrubs the root key from its OWN environment, stamps each child a scoped CREDZ_TOKEN, and re-injects the root key onto the kms broker child's Env ALONE. Every generic child comes up with a token and no key and must ask the broker. Pinned by cmd/cloud/main_test.go and proven by a live dns spawn. helm flag forwarding: cmd/cloud accepts --brand/--domain/--data-dir/--iam-issuer (the args the chart passes the entrypoint) and republishes each non-empty one as its CLOUD_* env, which the per-app children read; an empty flag never clobbers a value already pinned in the environment. console at "/": nothing served the host root once mountConsole moved into the per-app cloud.Serve. Extract the console into a light webui leaf (stdlib + embed + a new strings-only brand leaf, both aliased back into package cloud so no call site changes) so cmd/cloud — the front door — owns "/" and serves the white-labelled SPA. The host stays ~399 packages and imports zero subsystems. Co-authored-by: Hanzo Dev <dev@hanzo.ai>	2026-07-28 12:37:17 -07:00