cloud

func AbuseGate ¶ added in v1.801.381

func AbuseGate(deps Deps, t *edge.Traffic) zip.Handler

AbuseGate returns the lifecycle-defense middleware. t is the shared edge sensor; deps carries the policy store, the logger and the metering client.

It is a no-op passthrough when the sensor is absent, mirroring every other gate on this path: an unwired deployment is never blocked.

func Accepted ¶ added in v1.801.299

func Accepted(ctx context.Context)

func AccountFromPrincipal ¶ added in v1.801.186

func AccountFromPrincipal() zip.Handler

func App ¶ added in v1.801.307

func App(name string, cfg *Config, deps Deps, tools zip.Source) *zip.App

App returns an app carrying everything a Hanzo program must carry, in the one order those parts are correct in. It is the only way to obtain one: a program mounts its subsystem on what it gets back and never builds a zip.App itself.

The point is what a caller no longer has the opportunity to forget. Identity is not an option a program passes, it is a property of the value it receives, so a program is either holding an app that identifies its callers or it is holding nothing. Every other member here was equally forgettable and was equally forgotten: the o11y binary assembled its own app and reached production with no panic recovery, no request id, no response-header posture, no tracing, no request log and no typed-op enrichment — a shape nobody chose and nobody could see, because there was nothing to compare it against.

WHERE THE EDGE IS. Production runs ingress → gateway → the front door (cmd/cloud) → this program. The gateway is the public edge and owns rate limiting for the internet. The front door installs no middleware of its own — it routes, serves the console, threads operator flags and scopes credentials — so a program built here is its OWN edge and defends itself. That is why the browser and flood defenses are here rather than borrowed from a parent. A program reached over the plane socket instead trusts what its host asserted: the kernel answers which process is calling, and the boundary's findings travel with the request.

name is what the program calls itself in a diagnostic. tools is the MCP surface, which only a program holding a subsystem list can project — everyone else passes nil and serves none.

func As ¶ added in v1.801.350

func As(c *zip.Ctx, org string) context.Context

As delegates THIS request's principal to a call, pointed at a named tenant.

It is for the operator acting on someone else's books: a SuperAdmin migrating org X carries their own identity — which is what the callee re-checks — while the tenant being read is X, not the admin's own org. c.Forward() alone cannot express that, deliberately: it propagates the gateway's assertion unchanged, and the assertion says the admin's org.

So the principal is carried WHOLE and only the tenant is re-pointed, on a context with no request behind it, which is the one place zip reads a stated caller. The authority still comes from the gateway — every other field is the one it minted — and the callee applies its own rules to it. A caller that was not admitted as an admin gains nothing by naming another org, because naming the org was never what granted anything.

org empty keeps the caller's own tenant, so this is also the plain "delegate me" form for a call made from a handler that has no other tenant in mind.

func Ask ¶ added in v1.801.350

func Ask[In, Out any](ctx context.Context, app, op string, in *In) (*Out, error)

Ask is the whole client half: dial the app, invoke the op, close.

Prefer the GENERATED client for the peer (plane/<app>) — it is this call with the app name, the op name and the In/Out pair already fixed to each other, so the compiler checks what only a running fleet could check here.

func AuditTrail ¶ added in v1.786.1

func AuditTrail(rec *audit.Recorder) zip.Handler

AuditTrail returns the audit middleware bound to rec. A nil rec makes it a no-op passthrough so callers always Use() it unconditionally.

func BYOFeeBps ¶ added in v1.801.186

func BYOFeeBps() int64

BYOFeeBps resolves the BYO inference platform fee (basis points) from CLOUD_AI_BYO_FEE_BPS, else the policy default. A negative/invalid value falls through to the default so a typo cannot silently zero out the fee; 0 is honored (free BYO). This is the ONE BYO fee knob for the whole binary.

func BYOFloorMicros ¶ added in v1.801.186

func BYOFloorMicros() int64

BYOFloorMicros resolves the per-call BYO floor (micro-USD) from CLOUD_AI_BYO_FLOOR_UUSD, else the policy default. A negative/invalid value falls through to the default.

func BYOInferenceFeeMicros ¶ added in v1.801.186

func BYOInferenceFeeMicros(tokens int) int64

BYOInferenceFeeMicros is the per-CALL platform routing fee (micro-USD) for a BYO inference of `tokens` tokens: BYOFeeBps of the EQUIVALENT metered price (aiPriceUUSDPer1kTokens), FLOORED at BYOFloorMicros. A BYO model invoked with the org's own provider token (Cloudflare Workers AI) debits the SAME usage spine and the SAME per-scope caps as a Hanzo-served call, at the thin BYO fee — but never below the floor, so a call the token estimate CANNOT price (a non-text modality: 0 tokens) is still gated and billed rather than slipping through free and unchecked. This is the ONE BYO fee model — no per-provider variant.

func Billable ¶ added in v1.801.242

func Billable(method, path string) bool

Billable reports whether a request CONSUMES resource somebody has to pay a provider for, and therefore requires standing before it runs.

THIS IS THE BUG THE SPLIT EXISTS TO KILL. Authorization and pricing were one int64: DefaultPrice returned the edge charge, and BillingGate read `cents <= 0` as "do not gate". Every LLM path prices at 0 there — deliberately, because the ai and zen subsystems meter their own token costs and an edge charge would double-bill — so "we charge nothing HERE" silently meant "we authorize NOTHING here", and the same fusion made every resource kind an operator prices at 0 un-gated as well (ResourceMeter.Gate: `costCents <= 0 -> nil`). One int64 answering two questions is why the LLM leak and the non-LLM gap are a single bug. They are two questions now: Billable says WHETHER standing is required, DefaultPrice says WHAT the edge charges. Pricing something at zero can no longer un-authorize it.

READS ARE NEVER BILLABLE. GET/HEAD/OPTIONS pass unconditionally — gating reads already caused one outage, a balance view that 402s is unusable, and no read this binary serves calls a paid provider.

The path sets are MEASURED, not invented:

• inference — the exact paths zen's Claim owns (zen@v1.4.2 proxy.go) plus ai's own tree. These are the free-inference hole.
• meteredTrees — meteredApps resolved through the manifest (the non-LLM auth-not-balance gap). It must agree with the composition root: every surface that declares cloud.Metered spends a provider's money and therefore needs standing, and TestMeteredSurfacesRequireStanding fails if the two drift. The exceptions are named there, not guessed here: commerce is the pay path itself and o11y is telemetry ingest, so both charge nothing and declare cloud.Free.

func BillingGate ¶ added in v1.786.1

func BillingGate(m *metering.Client, price func(c *zip.Ctx) int64) zip.Handler

BillingGate returns a zip middleware that gates every request on the caller's commerce balance and records usage for priced paths.

Order of operations:

1. price(c) == 0 AND not gated → pass straight through (free path).
2. Authorize(ctx, identity) BEFORE c.Next(): nil → allow. ErrInsufficientBalance → 402 insufficient_balance, c.Next() NOT called. other error → 503 balance_unavailable, c.Next() NOT called (fail-closed; the client returns nil here when built FailOpen, so this branch never fires in fail-open mode).
3. c.Next() runs the handler chain.
4. After a successful chain, if price(c) > 0, fire `go m.Record(...)` so the debit never blocks or corrupts the response the user already received.

When m is nil or not configured (no commerce URL) the gate is a no-op: it returns c.Next() directly so an unconfigured deployment is never blocked. price must not be nil; pass DefaultPrice.

func Bridge ¶ added in v1.801.299

func Bridge() zip.Handler

Bridge carries into a typed op the request facts its signature drops, and carries back out the one fact it cannot state. Install it BEFORE the typed routes it serves — fiber runs middleware in registration order, so one installed after its leaves never runs — and after the identity boundary, so the identity it parks is the validated one.

It parks the TWO facts a gate turns on, in ONE expression, so they are always set together and can never disagree: the validated ORG (principal.WithOrg, for a plane with rows to scope) and VALIDATED-NESS itself (principal.WithValidated, for a plane whose reads are deployment-global and whose gate is therefore authentication). Both are read back through principal, so a gate that needs either does not reach for the request.

func CallerBearer ¶ added in v1.801.89

func CallerBearer(c *zip.Ctx) string

CallerBearer returns the caller's validated JWT bearer for RELAY to a downstream org-scoped service (e.g. the DNS control plane) that authorizes on the caller's OWN identity and derives the org from the token's `owner` claim. It returns the SAME token SanitizeIdentity validated the principal with (callerToken), UNCHANGED -- cloud substitutes NO service credential of its own, so tenant isolation carries across the hop: a caller in org A relays an org-A token and can reach only org A.

An opaque API key (pk-/sk-) is NOT a relayable bearer -- an OIDC target cannot validate it and forwarding it would leak the key -- so it returns "". Empty when the request carries no validatable bearer; the relay then sends no Authorization and the downstream fails closed on its own gate.

func ClientCountry ¶ added in v1.801.463

func ClientCountry(c *zip.Ctx) string

ClientCountry is the jurisdiction our edge resolved the caller from, or "" when nothing trustworthy said.

IT IS THE SAME TRUST RULE AS ClientIP, applied to a header instead of a chain, and it is written beside it so the two cannot drift into two rules. A header is a claim; what makes a claim readable is WHO the socket peer is:

a direct caller's header is the CLIENT's own writing. It is refused outright
— reading it would let any caller state its own jurisdiction, which on a rule
that escalates on geography is the same as switching the rule off.

a trusted peer's header is our EDGE's, written after the edge resolved the
address it saw. That is the only version of this fact anybody here holds.

WHAT IT IS NOT. It is the country of the ADDRESS, never of the payer: an address is what a VPN moves and a proxy relays, so this is a weak signal by construction and is documented as one at its one consumer. The strong signal — the billing or KYC jurisdiction of the account — is not derivable in this binary today (there is no billing address, no KYC profile, and the card never touches this process), and inventing one from this would be worse than stating that.

The value is normalised to upper case and refused unless it is exactly two letters. Cloudflare states "XX" for an address it could not place and "T1" for Tor, and neither is a country; both fail the letters test and come back "", which is the same answer as silence and the correct one — no jurisdiction was established.

func ClientIP ¶ added in v1.786.1

func ClientIP(c *zip.Ctx) string

ClientIP is the caller's own address: the socket peer for a direct caller, the right-most non-proxy entry of the forwarded chain for a proxied one, and "" for an in-cluster caller that never transited the edge.

It is the ONE client-address read in this repo — the edge rate limiter, the abuse sensor, the audit trail and every metered resource share it, so a forgeable address cannot enter one of them by a side door. It reads EVERY X-Forwarded-For header line, not just the first. fasthttp keeps repeated headers as separate lines, and a client that sends its own line before the proxy appends to a second one would otherwise hide the real address behind a value it chose.

func DataDir ¶ added in v1.801.299

func DataDir() string

DataDir resolves the data root from the environment. It is exported and split out of LoadConfig because credz.Boot must find the same directory BEFORE LoadConfig runs — the credential broker's socket lives there, and the credentials have to be installed before anything reads config or opens a store.

The rule itself lives in internal/datadir because the ROUTER needs it too, and the router cannot link this package. It takes the pod's writer lease on a file under this root before it spawns the children that open stores under it, so the two must resolve the same directory or the lock guards nothing.

func Declare ¶ added in v1.801.293

func Declare(specs []Plugin, cfg *Config)

Declare installs the composition root's boot snapshot — the inventory, the prefix table every traced request resolves against, and each surface's declared Price. A disabled subsystem is inventoried but claims NO prefix: it serves nothing, so letting it own a path would attribute another subsystem's requests (or a 404) to it.

MountAll calls it before anything mounts, and that is the only call a running binary makes. It is exported for the tests that must ask what the REAL composition root declares — apps.Wire() — without booting 111 subsystems' stores and dialling their providers to find out. Those tests are why the price a request resolves to can be checked against the number a reviewer approved.

func DefaultPrice ¶ added in v1.786.1

func DefaultPrice(c *zip.Ctx) int64

DefaultPrice is cloud's per-request price (in cents) for the edge gate. It holds NO table: it reads the price the surface DECLARED at the composition root (App.Price → PriceOf, see price.go), so the number the gate charges and the number a reviewer approved are the same number, in one place.

It used to be the table, and its last line was `return 0` for anything unlisted — which made a new route free forever, silently, because free never errors. That default is gone: an unpriced surface now fails TestPriceDeclared before it can ship. Undeclared still charges nothing HERE (Price.Cents), because a missing declaration must break the build, never a customer's card.

Two things it does on its own:

• Health probes are Free regardless of the surface they sit under. A liveness probe that 402s hides whether the process is up, and /v1/<svc>/health is a route of the same surface as everything else under /v1/<svc> — so the moment any surface carries a positive price, its probe has to be exempted here or the exemption has to be written 111 times.
• A surface declared Metered charges 0, because its meter is downstream: an edge charge on top of it bills the same work twice. That is Price.Cents's job, not a prefix list's.

func Degradations ¶ added in v1.801.256

func Degradations() map[string]string

Degradations returns subsystem → reason for every plane that mounted fail-closed. The result is a COPY: a caller must not be able to edit the registry through the map it was handed.

func Degraded ¶ added in v1.801.256

func Degraded(subsystem string, err error)

Degraded records that subsystem mounted fail-closed because of err. Calling it twice keeps the FIRST reason: the first failure is the cause, later ones are usually its echo.

func Denied ¶ added in v1.801.350

func Denied(err error) error

Denied turns a refused Gate into the error a TYPED op returns. Pair it with DenyEnvelope on the routes that can refuse; without the envelope the refusal still carries the right status and sentence (Unwrap), just in zip's shape.

func DenyEnvelope ¶ added in v1.801.350

func DenyEnvelope() zip.Handler

DenyEnvelope writes a Denied refusal back as the money wire's own bytes. Install it on the group whose typed ops gate on balance — and BEFORE those routes, since fiber runs middleware in registration order — so the REST projection answers the 402/503 contract it always has. Anything else passes through untouched.

func DenyResource ¶ added in v1.786.1

func DenyResource(c *zip.Ctx, err error) error

DenyResource renders the Gate denial outcomes as the SAME JSON the edge gate returns (denyBilling), so every Hanzo surface emits one error contract: 402 insufficient_balance / 503 balance_unavailable.

It WRITES the response, which is what an untyped handler wants and what a typed op cannot use: zip stamps the op's own status over a hand-written one after the handler returns, so a typed op refuses with Denied instead.

func Describe ¶ added in v1.801.350

func Describe(dir string, app *zip.App) error

Describe writes app's projection into dir: the OpenAPI document, from the one live router.

JSON, because JSON is what it IS — the same bytes served at /v1/openapi.json and dropped into hanzoai/openapi. Encoding to YAML would put a yaml library in the graph of every app binary to write a file only the weave reads. Indented so a subset reviews as a diff.

It is rendered whole before the file is touched, so a projection failure leaves the previous one intact rather than truncating it into an app that appears to serve nothing.

func DescribeRequested ¶ added in v1.801.350

func DescribeRequested() (string, bool)

DescribeRequested reports whether argv asks this binary to describe itself, and the DIRECTORY it named: `<binary> describe <dir>`. Read before any flag parsing — the mode is a mode, not an option.

A DIRECTORY and not stdout, and the argument is required. A subsystem's own dependencies write to stdout at mount (hanzoai/commerce prints a sqlite-vec warning and GORM debug lines), which a `> file` redirect splices into the front of the document and turns into 71KB of invalid JSON. A writer whose output an unrelated library can corrupt is not a writer.

func Draining ¶ added in v1.801.231

func Draining() bool

Draining reports whether a graceful shutdown is in progress.

func EdgeCORS ¶ added in v1.786.165

func EdgeCORS(pol *edge.Store) zip.Handler

EdgeCORS returns the browser-CORS middleware for the public /v1 edge. The origin allowlist is the PLATFORM policy's CORSOrigins, read live (recompiled only when it changes) so a SuperAdmin can add/remove origins via PUT /v1/gateway/config.

DEFAULT OFF (empty allowlist ⇒ no-op passthrough). On the RECOMMENDED rollout — the shared Traefik ingress keeps fronting api.hanzo.ai and its `cors-allow-all` middleware already answers CORS there — enabling cloud CORS too would emit a SECOND Access-Control-Allow-Origin header and break every browser preflight. So CORS stays owned by exactly ONE layer: the ingress until/unless the edge moves to a direct DO-LB→cloud path (cloud terminates TLS for api.hanzo.ai), at which point the operator sets CLOUD_CORS_ORIGINS (or PUTs it) and cloud becomes the sole CORS authority. One policy, one place — never both.

When enabled it handles the OPTIONS preflight itself (204, short-circuit) and reflects the allowlisted Origin on the actual response, then continues the chain.

func EdgeRateLimit ¶ added in v1.786.165

func EdgeRateLimit(pol *edge.Store) zip.Handler

EdgeRateLimit returns the per-client-IP flood cap that runs BEFORE identity — the gateway's `qos/ratelimit/router` (strategy:"ip") role. The limit + window are read LIVE from the PLATFORM policy (per_ip_rpm / window_sec), so a SuperAdmin can retune the cap via PUT /v1/gateway/config with no redeploy. It is a fixed-window counter keyed on the client IP (leftmost X-Forwarded-For, via ClientIP) with opportunistic eviction of expired windows so the map stays bounded even at the edge's high IP cardinality (why this is not the zip token-bucket primitive that ScopeRateLimit reuses: that primitive never evicts, which is fine for a bounded per-org keyspace but would grow without bound keyed on raw IPs).

SCOPE = public edge only. A request with NO X-Forwarded-For is an IN-CLUSTER direct caller (console BFF, sibling service hitting cloud.svc:8000) — it never transited the ingress/LB, exactly the traffic the standalone gateway never saw, so it is not IP-limited here (parity: the gateway only ever rate-limited public traffic). Only proxied edge traffic, which carries the real client IP in XFF, is throttled. A per_ip_rpm of 0 (env CLOUD_EDGE_RATELIMIT=false at boot) is a live no-op.

func EmbeddedTasks ¶ added in v1.786.72

func EmbeddedTasks() *tasksengine.Embedded

EmbeddedTasks returns the ONE in-process tasks engine, or nil until wireDurableIngest has run (or if it failed to start). The Tasks HTTP/UI surface (apps/tasks, mounted at /v1/tasks/*) serves on THIS shared engine — there is exactly one engine per process, shared by ai's durable ingest AND the Tasks product surface, never a second Embed. The surface resolves it lazily (per request) because subsystem Mount runs during MountAll, before wireDurableIngest.

func EmitLifecycle ¶ added in v1.800.1

func EmitLifecycle(ctx context.Context, ev LifecycleEvent)

EmitLifecycle fans one event out to every registered subscriber, best-effort and NON-BLOCKING: each subscriber runs in its own goroutine on a cancel-immune context (the fact already happened — a request cancel must not abort the notify/mirror), so a slow reactor (a mirror push) can never delay the git/deploy path or another reactor. A panicking subscriber is contained so one bad reactor can neither crash the shared multi-tenant process nor starve the others; each subscriber logs its own errors.

func EnsureGitMirror ¶ added in v1.801.59

func EnsureGitMirror(ctx context.Context, org, project, repo, url string, enabled bool) error

EnsureGitMirror registers (enabled) or removes (disabled) the outbound mirror target url on the native repo. Idempotent.

func ErrorHandler ¶ added in v1.801.381

func ErrorHandler(c fiber.Ctx, err error) error

ErrorHandler renders any error a handler propagates. Give it to zip.Config so the app has one, rather than the default that reads only *zip.HTTPError.

It is also the ONE place a fault is recorded. Every 5xx is logged whole — including the ones whose sentence DID survive to the wire, because an operator wants the wrapped chain and the client only ever sees the outermost sentence — with the request id that ties the log line to the response the caller holds.

func EstTokens ¶ added in v1.801.186

func EstTokens(texts ...string) int

EstTokens is a deterministic, provider-agnostic token estimate (~4 chars/token) used to price embeddings (no usage returned) and to pre-gate chat before the completion tokens are known.

func Facts ¶ added in v1.801.381

func Facts(m map[string]string) map[string]string

Facts drops the empty values from a signal map, because a fact we do not have must be ABSENT rather than empty. An empty string is a VALUE: a scorer keying velocity on "ip" would group every request whose address never arrived — which, behind a load balancer that does not pass the peer, is all of them — into one very busy caller and refuse the lot. "We do not know" and "it is the empty string" are different answers and only one of them is true.

Stated once, at the seam every question passes through, so no gate has to remember it.

func Fail ¶ added in v1.801.231

func Fail(c *zip.Ctx, msg string) error

Fail writes a { status:"error", msg } envelope. The operator's transport maps a non-ok envelope to a surfaced error (never a fabricated value).

func Fingerprint ¶ added in v1.801.381

func Fingerprint(cred string) string

Fingerprint turns a credential into a stable per-process handle. It is what the sensor counts under and what a traffic report shows — the credential itself never enters a counter, a log, a record or a response.

HMAC-SHA256 rather than a bare hash: with a bare hash, anyone holding a candidate key could confirm it against a published fingerprint. With a keyed digest under a salt that never leaves the process, they cannot.

func For ¶ added in v1.801.350

func For(ctx context.Context, org string) context.Context

For states the tenant a BACKGROUND call acts for — a reconcile loop, a grant issued when an org opens, a meter that debits after the response has gone out. Each acts for a tenant with no request to forward, and the callee has to know which one to write to the right books.

An inbound request always wins over this (zip prefers the gateway's assertion), so it supplies an identity where there is none and can never launder one.

func GitRepoStatuses ¶ added in v1.801.23

func GitRepoStatuses(ctx context.Context, org, project string, names []string) (map[string]GitRepoStatus, error)

GitRepoStatuses returns the per-repo import + sync status for names (org-scoped).

func Go ¶ added in v1.801.261

func Go(log luxlog.Logger, name string, fields []any, fn func())

Go runs fn on a new goroutine with its panic CONTAINED.

This is the one spawn helper for background work in the shared binary, and it exists because of an asymmetry that is easy to miss: middleware.Recover() wraps only the goroutine serving the request. A panic on any goroutine that a handler SPAWNS is unrecovered, and an unrecovered panic does not fail that request — it takes the process down, and with it every tenant and every subsystem in the binary. A malformed page fetched during one org's search would stop everyone's chat.

The surface is large and fed by untrusted input: web pages we fetch and parse, documents we decode, payloads from platforms we bridge. Those are exactly the paths most likely to panic and least likely to be exercised in tests.

name is what appears in the log if fn panics — make it identify the work ("crawl.fetch", "answer.read"), not the call site, because that is what someone reads at 3am. fields are appended verbatim, so pass the org or job id that makes the line actionable; never pass a secret.

It deliberately does NOT return an error, wait, or restart. A caller that needs a result uses a channel; a caller that needs bounding takes a limiter FIRST and releases it in fn (register the release defer before calling Go, so it survives the panic). Containment is this helper's only job.

func Guard ¶ added in v1.801.350

func Guard(s Scope, h zip.Handler) zip.Handler

Guard applies the rule to a handler in the standard way: an inadmissible caller is refused 403 before the handler runs, so nothing behind the gate ever observes an unauthorized request.

A subsystem whose REFUSAL has a different shape (the deploy console sends a browser navigation to sign-in) calls Admits directly instead. That is a difference in the answer, not in the rule — the rule is still read from here.

func Handle ¶ added in v1.786.216

func Handle[S any](s *Service[S], h func(*Service[S], *zip.Ctx) error) func(*zip.Ctx) error

Handle binds a Service-scoped handler to a route: it adapts a `func(*Service[S], *zip.Ctx) error` to the plain `func(*zip.Ctx) error` the router takes, capturing s. One adapter, so packages write free-function handlers and register them with `app.Get("/path", cloud.Handle(s, myHandler))`.

func IAMBase ¶ added in v1.801.408

func IAMBase() string

IAMBase is IAMBaseURL against this deployment's OWN issuer — what a caller with no Config value in hand uses. It exists so "which IAM do I call" has one answer whether or not the caller happens to be holding a Config: three callers resolved it themselves and grew three different fallbacks (the public issuer, nothing at all, and a hardcoded cluster address), which is the disagreement this file was written to prevent and did not.

func IAMBaseURL ¶ added in v1.801.293

func IAMBaseURL(publicIssuer string) string

IAMBaseURL resolves the IAM base URL a SERVER-SIDE caller inside the cluster should use — the split-horizon policy, stated once.

The public issuer host (e.g. https://hanzo.id) is fronted by Cloudflare, which 403s a server-side loopback POST with edge error 1006 — so an in-cluster exchange against the public issuer fails and whatever depended on it (the KMS login broker, AI M2M minting, per-tenant identity provisioning) silently stays down (root-caused 2026-07-04: in-cluster POST to https://hanzo.id/... → 403, while http://iam.hanzo.svc/... → 200).

Precedence: the in-cluster IAM service base (IAM_URL — already wired for JWKS), then the public issuer as a last resort (single-process / no split-horizon deploys). Returns "" only when no IAM is resolvable at all. This existed as three inlined copies (ai M2M, the KMS login broker, and the per-tenant identity provisioner would have been the fourth); a copy of a policy does not disagree until one is edited, so there is exactly one now. Endpoint-specific overrides (CLOUD_AI_IAM_TOKEN_URL, CLOUD_KMS_IAM_TOKEN_URL) stay with their endpoints — they override a URL, not this policy.

func IAMExternal ¶ added in v1.801.408

func IAMExternal() bool

IAMExternal reports whether this deployment NAMES a separate IAM, as opposed to being the IAM itself (the embedded subsystem).

It is a different question from IAMBaseURL — "is there another IAM" versus "what is its address" — and it is here because answering it separately is how the two disagree: a deployment with only a public issuer resolves a non-empty base yet names no external IAM, and a caller that inferred one from the other reached for a store that is not there.

func IAMIssuer ¶ added in v1.801.408

func IAMIssuer() string

IAMIssuer is the PUBLIC identity host this deployment presents (hanzo.id). One name for one fact: the issuer stamped into a token and the issuer a validator checks are the same string, so they are read in one place.

func Identify ¶ added in v1.801.437

func Identify(app *zip.App, cfg *Config)

Identify gives an app a trustworthy answer to who is calling, and makes that answer reachable from every route beneath it. App does this for every program, which is the only reason it can no longer be skipped.

The two halves are one function because each is wrong without the other, and wrong in a way nothing reports. IdentityMiddleware deletes the authority headers a client sent and re-mints them from a verified IAM token, so it runs first: what it produces is the only principal in the process anyone may trust. The enrichment then parks that principal on the request context, which is the only path by which a typed op reaches it — a zip.Get[In, Out] handler receives a context and its decoded In and nothing else. Reversed, it parks whatever the caller claimed for itself. Installed alone, the boundary validates a caller and then every typed op reads an empty org and refuses that same caller, which reaches the wire as a 403 from a service behaving exactly as built.

That last failure is the reason this is a function rather than two lines of advice. It is what the o11y binary did while assembling its own app, and its subsystem then compensated from inside its own Mount, on a group node that owned no routes — a program zip refuses to compose, which is the outage.

func IdentityMiddleware ¶ added in v1.786.72

func IdentityMiddleware(cfg *Config) zip.Handler

IdentityMiddleware builds the identity trust-boundary middleware from cfg: it constructs the IAM JWT validator (trusted-issuer set, JWKS, audience allowlist) and returns SanitizeIdentity bound to the admin org. This is the ONE constructor for the boundary, so Serve and integration tests wire it identically — no second copy of the validator-construction glue to drift.

func ImportGitRepo ¶ added in v1.801.23

func ImportGitRepo(ctx context.Context, req GitImportReq) error

ImportGitRepo creates + mirrors an external repo into the native git server.

func InstallTelemetry ¶ added in v1.801.299

func InstallTelemetry(ctx context.Context, log luxlog.Logger, serviceName string) func(context.Context)

InstallTelemetry installs this process's OTel tracer and meter providers and returns a shutdown that flushes and stops both. The returned func is ALWAYS non-nil, so callers defer it unconditionally.

Call it ONCE per process, from the composition root, BEFORE anything mounts. Serve does exactly that — so every per-app plugin entrypoint, which shares its body, installs identically and before ai mounts and reads the adopted-ready flag. It is exported because Serve is not the only composition root: a plugin binary (plugin/o11y) is a host for its own requests and needs the same providers, and one bootstrap that every root calls is the only way that stays true. No root writes its own.

An operator may override serviceName at runtime with OTEL_SERVICE_NAME.

func IsBotActor ¶ added in v1.801.293

func IsBotActor(login string) bool

IsBotActor reports whether a push actor is an automation identity rather than a person. Every inbound push transport asks this BEFORE firing OnGitPush: our own release and mirror automation push AS these identities, so without the guard a release's own commit triggers the next release, forever. The two wires we ingest spell a bot differently — GitHub suffixes App-authored logins with "[bot]", our forge attributes workflow-made pushes to its Actions system user — so the ONE predicate knows both.

func IsCommit ¶ added in v1.801.455

func IsCommit(s string) bool

IsCommit reports whether s names a git commit: a full 40-char lowercase hex object name, exactly.

It is the ONE rule for that, applied at BOTH ends of the same wire — the builder refuses to pass build-arg:REVISION unless it holds (apps/platform), and this process refuses to report a value unless it holds — so the two cannot drift into disagreeing about what they hand each other. A builder rule laxer than the reader's would pass a branch name that silently became "unknown", which is this outage's failure mode wearing a different hat.

func IsPublishableKey ¶ added in v1.801.231

func IsPublishableKey(tok string) bool

func KMSMachineClientID ¶ added in v1.801.293

func KMSMachineClientID(org string) string

KMSMachineClientID is the clientId an org's dedicated PaaS-KMS sync application carries — which is also, by the contract above, the audience its tokens are stamped with. Exported for the provisioner (clients/platform), so "<org>-platform-kms" is derived in exactly one place: here, where the recognition side (isKMSMachinePrincipal) reads it back.

func KeyHint ¶ added in v1.801.360

func KeyHint(key string) string

KeyHint is the ONE way a key is named in a log line or an error message: its prefix and nothing else. A credential must never be echoed whole, and "sk-902abd…" is enough for a holder to tell WHICH of their keys failed while being useless to anyone who intercepts it.

func Listen ¶ added in v1.801.307

func Listen(plugins []Plugin, enable []string) error

Serve boots the canonical compose root and mounts the selected subsystems.

This is the ONE place the cloud-server body lives — every per-app plugin main (plugin/<app>/main.go) calls it, so no boot logic is duplicated per subsystem.

plugins is the composition root's subsystem list (apps.Wire()), threaded in by the caller so cloud never imports subsystems (which would cycle). Listen mounts it in slice order and tears it down in reverse.

enable==nil ⇒ honor cfg.Enable from flags/env (cloud mode; empty = all). enable!=nil ⇒ force exactly that set (single-service mode), overriding --enable so `hanzo kms` is unambiguous.

Listen registers the HIP-0106 liveness contract (GET /v1/<name>/health for every enabled subsystem) before MountAll, runs the canonical middleware pipeline (Recover → RequestID → Logger), and shuts down gracefully on SIGINT/SIGTERM.

func MarkdownNegotiation ¶ added in v1.786.165

func MarkdownNegotiation(defaultPrefixes []string) zip.Handler

MarkdownNegotiation returns the response-path middleware. Register it ONCE at the compose root and every /v1 endpoint negotiates markdown uniformly.

func Members ¶ added in v1.801.299

func Members(deps Deps) []ha.Member

Members is the writer set this process believes in: the LIVE set when the durable plane elects one, else the static CLOUD_PEERS set the router falls back to. Empty means a single-pod deployment, where this process is the whole fleet.

Exported because the plugin control plane fans out over the membership — and it must be the SAME membership the shard router routes on. Two fleet views that could disagree would be worse than one that is occasionally stale: an operator would roll a version onto a set of hosts that is not the set serving traffic.

func MetricGatherer ¶ added in v1.801.381

func MetricGatherer() prometheus.Gatherer

MetricGatherer exposes the registry for the in-process push to the telemetry store (apps/o11y/metricspush.go), which is the ONLY way measurements leave this process now that Prometheus is retired.

The registry is no longer a PUBLISHED SURFACE — there is no exposition and no scraper — it is the buffer the meter provider renders into and the push drains, in the same family model the datastore receiver already speaks. Handing out the Gatherer rather than the *Registry keeps the rule this registry exists to enforce: what appears here is what this process chose to instrument, so a reader cannot quietly become a registrant.

func MicrosToGateCents ¶ added in v1.801.186

func MicrosToGateCents(micros int64) int64

MicrosToGateCents converts a micro-USD amount to the whole cents a pre-call balance gate must RESERVE: round UP (a gate must never under-reserve), with a 1-cent floor for any positive amount. 1 cent = 10_000 micro-USD. Shared by the LLM meter and every other inference path (Workers AI) so one rule prices the gate everywhere.

func Mount ¶ added in v1.786.216

func Mount[S any](app Router, deps Deps, name string, build func(Base) (S, error), routes func(Router, *Service[S])) error

Mount is the one generic subsystem entrypoint. `build` constructs the typed State from Base (open stores, dial clients — returns an error to fail the mount closed); `routes` registers the handlers. A package's exported Mount is then one line: `return cloud.Mount(app, deps, "name", build, routes)`.

func MountAll ¶

func MountAll(app *zip.App, specs []Plugin, cfg *Config, deps Deps) error

MountAll mounts every ENABLED subsystem in specs, in slice order — the order is the composition root's (apps.Wire()); MountAll does NOT sort.

app is the concrete *zip.App from Serve. A Global spec receives it as its Router. Everyone else receives a scope bound to their declared Prefixes, so a subsystem's middleware reaches its own subtrees and nothing else, whatever its slice position. A subsystem that installs middleware outside them fails the mount — the binary refuses to boot half-gated rather than serving with a stranger's gate on.

Every spec goes through spec.Mount, whatever the grant: the Router it receives is the only difference, which is what makes MountFunc the fleet's ONE mount signature and lets the compiler check it at all 123 composition roots.

Teardown is wired HERE, at mount time: right after a subsystem mounts, its ShutdownFunc (if any) is registered via app.OnShutdown. zip drains those hooks LIFO — AFTER the listeners stop accepting and in-flight requests drain — so registration-at-mount yields reverse-mount teardown (a dependency mounted before its dependents is torn down after them) with no subsystem torn down while a request still uses it. Only ENABLED specs mount, so only they register a hook; teardown needs no separate enablement gate.

func MountMetrics ¶ added in v1.801.299

func MountMetrics(app Router, deps Deps) error

MountMetrics adapts hanzoai/metrics into a MountFunc. metrics declares its OWN narrow Deps (Logger, DataDir, Brand) and does not import hanzoai/cloud, so Typed cannot bridge it; this builds that Deps from cloud's and calls metrics.Mount.

It lives here rather than in package apps for exactly CtxShutdown's reason: an apps-local identifier in a Wire entry is unreachable from the generated plugin/<app>/main.go, so metrics fell back to the stub that links every subsystem. The move is affordable only because it is nearly free — cloud's core already carries 398 of metrics' 399 dependencies, so every binary grows by the one package hanzoai/metrics itself. It is the ONLY one of the four mount adapters that is: commerce would add 527 packages to the core, and zen (via hanzoai/ai/controllers) and ai import hanzoai/cloud — a cycle, not a weight.

It is a MountFunc — the doc above always CLAIMED it was one and the signature said otherwise, which is the whole reason a per-entry-point escape hatch is a bad idea. metrics installs no middleware anywhere (hanzoai/metrics calls Use nowhere), so it mounts SCOPED like everyone else; it only ever needed the concrete app to register routes, and cloud.ZipApp is the named hole for that.

func MountPrefixes ¶ added in v1.801.264

func MountPrefixes(name string, declared []string) []string

MountPrefixes is the ONE rule for which subtrees a subsystem owns: the prefixes it declared, else the /v1/<name> convention. scope's middleware gate and this index MUST agree on that rule, so they share this function instead of each spelling the fallback — a drift between them would mislabel every span of the subsystem that disagreed.

IT DOES NOT FALL BACK TO manifest.Apps, and the difference is worth stating because the two lists look interchangeable and are not. A manifest row answers "which paths does the HOST forward here" — a routing table, free to enumerate leaves: deploy's row is 14 specific paths (/v1/deploy/applications, /v1/deploy/clusters, …). This answers "which subtree may this subsystem's MIDDLEWARE gate", and deploy installs one bridge across /v1/deploy, the parent of all 14. Feeding the routing table in here made that bridge an escape and failed deploy's boot outright.

So a subsystem whose surface is not /v1/<name> states its own bound — `Prefixes: manifest.PrefixesFor(name)` where the two genuinely coincide, which is what referrals and 21 others do.

func MustOrgNamespace ¶ added in v1.801.360

func MustOrgNamespace(org, project string) namespace.Namespace

MustOrgNamespace is OrgNamespace for an org fixed in the source — a test, a seed, a constant in a migration. It panics, which is correct for a value that is wrong before the program runs and wrong for anything from a request.

func OK ¶ added in v1.801.231

func OK(c *zip.Ctx, data any) error

OK writes a { status:"ok", data } envelope (the get<T> shape).

func ObserveAlertDelivery ¶ added in v1.801.381

func ObserveAlertDelivery(egress, outcome string)

ObserveAlertDelivery records one alert batch's egress outcome. This is the metric behind the meta-alert: paging that cannot reach a human is itself an incident, and the only reason it went unnoticed for months is that nothing counted it.

func ObserveIngest ¶ added in v1.801.381

func ObserveIngest(door string, accepted, dropped int)

ObserveIngest records one ingest door's admission outcome.

accepted and dropped are reported TOGETHER because the useful question is a ratio, not a count: "88% of what was offered was dropped" is an outage, "8,000 items were dropped" is a number whose meaning depends on a second series nobody fetched.

func ObserveRows ¶ added in v1.801.381

func ObserveRows(table string, n int)

ObserveRows records rows landed in one event STREAM. Called from the two writers that put rows there — the o11y plane sink and the analytics bus drain — so `event.span` counts whichever one is carrying it.

The argument is the stream (event.span, event.log, event.act …), not the physical table: since the occurrence tables merged into event.fact the table no longer identifies what stopped. See warehouseTables.

func OnGitPush ¶ added in v1.786.216

func OnGitPush(ctx context.Context, ev GitPushEvent) error

OnGitPush fires the registered push-to-deploy trigger for a landed push. It is a no-op when no builder is registered (git server running without the platform subsystem co-resident). Best-effort by contract: the caller must never fail the push the client already committed just because a build could not be triggered.

func OnServiceRelease ¶ added in v1.801.7

func OnServiceRelease(ctx context.Context, ev ServiceReleaseEvent) error

OnServiceRelease rolls a proven image live by patching the matching hanzo.ai/v1 Service CR's spec.image (the operator then reconciles the Deployment). It is a no-op when no releaser is registered (a binary without the paas control plane co-resident). The releaser enforces the clean-semver gate and CR-name resolution; this is only the dispatch seam.

func OrgDB ¶ added in v1.786.216

func OrgDB(dataDir string, ns namespace.Namespace, subsystem string) (*sql.DB, error)

OrgDB is the ONE way any cloud subsystem opens a per-entity SQLite file (HIP-0302 physical isolation). It resolves the namespace to its path, creates the parent directory 0700, opens via the sole "sqlite" driver under that namespace's own key, and pins the pool to one connection. The caller owns migration (its schema is its own) and Close.

It takes the NAME rather than the parts a name is made of, so it cannot pair one namespace's path with another namespace's key, and so the question "could this have come from caller input" is asked once — at OrgNamespace, the only door — instead of again at every subsystem that opens a file.

Path convention — see namespace.Key:

org/{slug}            →  {DataDir}/orgs/{slug}/{subsystem}.db
org/{slug}/{project}  →  {DataDir}/orgs/{slug}/projects/{project}/{subsystem}.db
system                →  {DataDir}/orgs/_platform/{subsystem}.db

func OrgForKey ¶ added in v1.801.91

func OrgForKey(ctx context.Context, key string) (string, bool)

OrgForKey resolves an opaque Hanzo API key (pk-/sk-) to the org it belongs to — the SAME owner org SanitizeIdentity mints when that key arrives as a bearer — and is the exported door a keyed, bearer-less SDK path uses to attribute a project key to a tenant.

TWO doors in IAM, because a publishable key and a secret key are resolved by different questions and the answers must not be interchangeable:

• a SECRET key (sk-) asks WHO, and get-user?accessKey answers with the principal. IAM refuses a pk- there BY DESIGN (store.UserByAccessKey), which is right and was also the bug: cloud sent every prefix down this one door, so a publishable key resolved to nothing and the ingest path it exists for could never attribute a beacon. A publishable key that resolves to nobody is a publishable key that does not work.
• a PUBLISHABLE key (pk-) asks WHICH ORG, and resolve-key answers with the org and nothing else — no user, no email, no admin bit. That is the property that makes it safe to ship in client JS, so it is a separate door with its own narrower capability (CapPublishableResolve), not a flag on the first.

FAILS CLOSED: ("", false) for a non-key-shaped string, an unknown/unresolvable key, an unconfigured resolver, or an out-of-bounds org — never a fabricated or default tenant, so a bad key can never be written into another org's partition. The isAPIKey prefix gate keeps garbage strings off the IAM network path.

func OrgHasUnsafeRune ¶ added in v1.786.32

func OrgHasUnsafeRune(s string) bool

OrgHasUnsafeRune reports whether s carries any whitespace, control, or zero-width/format rune — the class that defeats the injectivity of the org→namespace map. strings.TrimSpace (and fasthttp's own header-value OWS trimming) silently drop such runes at the edges, so two DISTINCT IAM org names ("acme" vs "acme ", or an NBSP/ZWSP variant) would collapse onto ONE namespace / image ref — a cross-org fold. The identity trust boundary REFUSES to grant org-scoping from an org bearing one of these (fail secure) instead of folding it, so distinct raw names never collide and no namespace is ever derived from an invisible-character identifier.

Case / '-' / '.' / other visible punctuation are deliberately NOT unsafe: those fold INJECTIVELY through the slugger's hash. Only the invisible / edge-trimmable class — which no injective fold can survive once transport strips it — is rejected. A legitimate IAM org slug never contains such a rune, so no real caller is affected.

It is DERIVED from namespace.Sanitize rather than re-deciding the rune class, because the identity boundary and the slugger have to refuse exactly the same names: this predicate is the reason a request gets no org-scoping, and Sanitize's "" is the reason that org could not have named a database anyway. Two spellings of one rule is a rule that eventually disagrees with itself. The empty org is not "unsafe" — it names nothing, which callers already handle — so it is excluded, exactly as it was when the loop lived here.

func OrgNamespace ¶ added in v1.801.360

func OrgNamespace(org, project string) (namespace.Namespace, error)

OrgNamespace names the database an org's records live in — or, when project is non-empty, the database that org's records for one project live in.

org MUST be the VALIDATED principal value (principal.Org, and for the project scope principal.Project), never a raw request body or header. It IS namespace.OrgProject: the org is folded through the ONE injective slugger, so two distinct orgs can never share a namespace, and the project rides in the GROUP slot, which is what a group is for.

It stays spelled here, as cloud's name for that door rather than a second implementation of it, because "which values may name a database" is a question about cloud's principals — and TestOnlyOrgnsBuildsANamespace answers it by proving this file is the only one that asks.

func Peer ¶ added in v1.801.307

func Peer(app string) (*zip.Conn, error)

Peer opens a call to another app.

func Plane ¶ added in v1.801.350

func Plane() *zip.App

Plane is the app internal ops register on. Every app in this process shares it, because a process serves ONE canonical socket per app name and the ops behind it are that app's whole internal surface.

Declare an op on it exactly as on any app:

zip.Post[plane.SecretIn, plane.Secret](cloud.Plane(), "/kms/get", read,
    zip.WithOperationID(plane.KMSGet))

func Privileged ¶ added in v1.801.381

func Privileged(method, path string) bool

Privileged reports whether a request grants standing authority, and therefore whether the scorer's silence must deny it.

It normalizes the path FIRST and compares nothing before it has. That order is the whole fix: the grant lists below describe ROUTES, and a route is what the router says it is.

func Probe ¶ added in v1.801.381

func Probe(method, path string) bool

Probe reports whether a request is a liveness/readiness check. A probe is never a grant and is never screened — a health endpoint a risk decision can fail is not a health endpoint, and a kubelet is not a customer.

ONE predicate, read by both the gate's exemption and Privileged below, so the two can never disagree about what a probe is. Read-only methods only: a POST to something ending in "/health" is not a probe, so an attacker cannot name a mutating route into the exemption.

path is normalized here rather than by the caller, so a caller cannot forget.

func Reachable ¶ added in v1.801.242

func Reachable(path string) bool

Reachable reports whether a path must be served REGARDLESS of standing.

This is not a scope selector — which routes a gate guards is decided by where it is applied. It is a SAFETY PROPERTY: a customer who has not yet paid must still be able to reach the paths that let them pay, and a lapsed one must be able to cure their own lapse. Gate those and you deadlock every prospect and every lapsed customer at once — a self-inflicted total revenue stop that looks like success in a naive test, because everything returns 402. So the list lives INSIDE the predicate: no future wiring mistake can gate the pay path, whatever it wraps.

Gating too little is a revenue leak we fix next week. Gating too much is an outage. The list is therefore deliberately generous, and anything ambiguous belongs on it.

Traced from the console subscribe flow (console src/components/products/ PlansModule.tsx -> src/lib/api/plans.ts): PlansApi.plans() reads /v1/billing/plans through the per-tenant billing proxy, and checkout drives the /v1/billing/* money surface — which also carries the INBOUND PROVIDER WEBHOOKS at /v1/billing/webhooks/:provider. Gating an inbound payment webhook loses payments outright, so that prefix is load-bearing twice over.

func Refuse ¶ added in v1.801.242

func Refuse(c *zip.Ctx, product, reason string) error

Refuse renders the ONE 402 shape every spend gate uses. product is empty for the edge gate (which gates spend itself, not a product) and set by a product-scoped gate; `for <product>` is the only difference it makes to the sentence.

func RegisterCommerceClientFactory ¶ added in v1.786.216

func RegisterCommerceClientFactory(f func(cfg *Config, log luxlog.Logger) CommerceClient)

RegisterCommerceClientFactory installs the embedded-Commerce client constructor. apps/commerce.go calls this from its init(); exactly one registration.

func RegisterGitImporter ¶ added in v1.801.23

func RegisterGitImporter(g GitImporter)

RegisterGitImporter installs the git object-plane importer. nil-safe.

func RegisterGitMirrorController ¶ added in v1.801.59

func RegisterGitMirrorController(c GitMirrorController)

RegisterGitMirrorController installs the git-plane mirror controller. nil-safe.

func RegisterIssueSink ¶ added in v1.801.218

func RegisterIssueSink(fn IssueSink)

RegisterIssueSink installs the tracker upsert sink. nil-safe.

func RegisterKMSClientFactory ¶ added in v1.786.165

func RegisterKMSClientFactory(f func(cfg *Config, dur *org.Durability, log luxlog.Logger) (KMSClient, error))

RegisterKMSClientFactory installs the embedded-KMS constructor. clients/kms calls this from its init(); it is the ONE inversion point that lets the KMS library and its /v1/kms subsystem share one package with no cloud⇄kms cycle.

func RegisterLifecycleSubscriber ¶ added in v1.800.1

func RegisterLifecycleSubscriber(fn func(ctx context.Context, ev LifecycleEvent))

RegisterLifecycleSubscriber adds a git-lifecycle reactor. Every subsystem that reacts to a push/deploy (mirror-out, Slack-notify) registers ONE here at Mount; git/platform EMIT via EmitLifecycle. The inversion keeps the emitters from importing the subscribers — the same pattern as RegisterPushBuilder, but many-registrant.

func RegisterOrgScopeResolver ¶ added in v1.786.216

func RegisterOrgScopeResolver(r OrgScopeResolver)

RegisterOrgScopeResolver adds a project-ownership registry consulted by the identity trust boundary. Called once per registry at its Mount (mirrors sites.SetResolver). Registries COMPOSE: a project is "mine" if ANY registry owns it for the org, and "foreign" only if some registry owns it for another org while NONE owns it for this org. A nil resolver is ignored.

func RegisterPushBuilder ¶ added in v1.786.216

func RegisterPushBuilder(f func(ctx context.Context, ev GitPushEvent) error)

RegisterPushBuilder installs the git-push-to-deploy trigger. clients/platform calls this from its Mount when co-resident; it is the ONE inversion point that lets the embedded git server launch a platform build with no git⇄platform cycle.

func RegisterServiceReleaser ¶ added in v1.801.7

func RegisterServiceReleaser(f func(ctx context.Context, ev ServiceReleaseEvent) error)

RegisterServiceReleaser installs the first-party CR-rollout hook. clients/paas calls this from its Mount when co-resident; it is the ONE inversion point that lets a build-completion path roll a proven image onto its operator Service CR with no cloud⇄paas import cycle.

func RegisterSync ¶ added in v1.801.59

func RegisterSync(fn SyncFunc)

RegisterSync installs the sync reconcile func. nil-safe.

func RegisterTraceSink ¶ added in v1.801.299

func RegisterTraceSink(sink TraceSink)

RegisterTraceSink installs the co-resident span consumer; a nil sink deregisters it. clients/o11y calls this at mount (and with nil at teardown, so a late export falls back to the wire instead of writing into a closed exporter).

A registration is process-local BY CONSTRUCTION, and that is the mechanism that makes one code path serve both deployments: linked-in o11y registers here and wins the Cost-0 leg; plugin o11y registers in its OWN process, this router stays empty, and the exporter's identical Send falls through to the ZAP wire.

func RepoFromCloneURL ¶ added in v1.800.1

func RepoFromCloneURL(u string) string

RepoFromCloneURL extracts the repo name from a git clone URL (last path segment, ".git" stripped) — the repo component of the (org,project,repo) routing key that a deploy emitter derives from an app/project's linked RepoURL. The ONE place this derivation lives, shared by the platform + projects deploy paths (no per-package copy).

func Request ¶ added in v1.801.299

func Request(ctx context.Context) (*zip.Ctx, bool)

Request returns the request a typed op is serving, for the ops that must FORWARD the caller's identity rather than merely read it (see the package note). Absent off the HTTP path, where the honest answer is that there is no request — a caller that needs one refuses rather than inventing an identity.

func ResetLifecycleSubscribers ¶ added in v1.800.1

func ResetLifecycleSubscribers()

ResetLifecycleSubscribers clears the registry. TEST-ONLY seam (a test mounts and unmounts repeatedly); production registers once at Mount and never resets.

func ResetPlane ¶ added in v1.801.350

func ResetPlane()

ResetPlane drops the process's plane app and every op declared on it.

Mount runs again in tests, and zip's op registry APPENDS: a second registration of the same op sits BEHIND the first, so a test would be answered by a previous test's handler — with that test's state, silently, and looking like a pass. The hand-written registry this replaced allowed re-exposing a name because of exactly that, and this is where the property went.

A process mounts once, so nothing in production calls this.

func ResourceFeeCents ¶ added in v1.786.1

func ResourceFeeCents(envPrefix, kind string) int64

ResourceFeeCents resolves the flat create fee (in cents) for kind from operator config, most specific first:

<envPrefix>_<KIND>   e.g. CLOUD_PROVISION_FEE_CENTS_SQL=500
<envPrefix>          e.g. CLOUD_PROVISION_FEE_CENTS=100  (all kinds)
DefaultResourceFeeCents                                   ($1.00)

A clearly-named, configurable policy knob — never a fabricated price. A value of 0 makes the kind free (and un-gated). Negative/invalid values are ignored (fall through), so a typo can never make a paid resource free by accident.

func Revision ¶ added in v1.801.455

func Revision() string

Revision reports the commit this binary was built from, or "unknown".

UNKNOWN IS A VALUE, NOT A BLANK. Only a full 40-char lowercase hex object name is ever reported; an unexpanded "${REVISION}", a branch name, "dev", a short sha and the empty string all read "unknown". A near-miss is worse than no answer at all, because someone acts on it.

That matters here specifically: `-X` naming a symbol the linker cannot resolve is not an error, it is dropped SILENTLY. A stamp that reached nothing must therefore read as the loud, useless "unknown" rather than as something plausible — and the image build proves the stamp landed by grepping its own linked binaries, because a flag that was merely REQUESTED still appears in `go version -m` output when the symbol was never set.

func RiskScorerInstalled ¶ added in v1.801.381

func RiskScorerInstalled() bool

RiskScorerInstalled reports whether a scorer is available — for a health probe or a report, never as a gate. The gate is Decide, which handles absence itself.

func RoutePath ¶ added in v1.801.381

func RoutePath(path string) string

RoutePath is a request path in the form THE ROUTER MATCHES IT, and it is the only form a security comparison may use.

fiber resolves a route against its "detection path": the request path lower-cased (CaseSensitive is off) with trailing slashes stripped (StrictRouting is off). c.Path() is the raw spelling the client sent. So `/V1/KMS/secret` and `/v1/kms/` reach exactly the handlers `/v1/kms/...` and `/v1/kms` do, while a prefix test over the raw path matches neither — one capital letter turned a fail-CLOSED grant surface into a fail-OPEN one.

The rule here is the ROUTER'S rule, not an approximation of it: any other normalization would be a second opinion about what a path means, and the router's is the one that decides which handler runs. Percent-encoding is deliberately NOT decoded, for the same reason — fiber does not decode it either (UnescapePath is off), so `/v1/%6bms` routes nowhere and is not a bypass; decoding it here would make this function match a route that does not exist.

func SanitizeIdentity ¶ added in v1.786.1

func SanitizeIdentity(v *identityValidator) zip.Handler

SanitizeIdentity returns the identity-trust-boundary middleware.

Per request:

• ALWAYS delete every header in authorityHeaders (a client copy never survives — this alone kills X-User-IsAdmin forgery).
• Validate a Bearer / Basic / session-cookie JWT, if present: SuperAdmin (authz.Claims.PlatformSudo — a human MEMBER of the reserved admin org, at any position in the signed `orgs` set). Membership IS the predicate; the isAdmin bit is deliberately not a second term, and IAM does not mint one. This test used to read `homeOrg == adminOrg`, i.e. `Orgs[0].Org` — a POSITIONAL read that IAM's own ordering (home org always first) made true only for a user whose ROW lives in the admin org, so every operator granted admin-org membership was silently refused. → X-User-IsAdmin=true; X-Org-Id = the requested org when present (admin org-switch), else the home org. any other principal (incl. org admins, normal users) → X-Org-Id pinned to owner; NO admin. A client org cannot widen scope.
• No / invalid / opaque-API-key credential: → NO admin (forgery dead), and the client's X-Org-Id is restored for the Phase-1 data path (residual below).

PHASE-1 RESIDUAL (documented; not a regression vs. today): with no validatable bearer, the client X-Org-Id is passed through for DATA scoping. cloud's data plane has no session of its own yet ("Auth stays gateway-owned in Phase 1") and the console browser data path depends on this header. So a direct-to-pod caller can still SELECT an org for DATA reads. Closing that needs the data path to carry a bearer universally OR the NetworkPolicy locked to gateway-only (which would break console's legitimate direct in-cluster BFF) — Phase-2. The ADMIN boundary (this fix's P0) is closed on every path regardless, because X-User-IsAdmin is NEVER restored from client input.

FAIL MODE. If the validator can't verify a token (JWKS unreachable on a cold cache, issuer/audience misconfigured), the request resolves anonymous and BOTH planes fail SECURE. Admin fails closed (X-User-IsAdmin is never restored from client input), and — since F1 — the DATA plane fails closed too: it gates on a validated principal (clients/principal.Validated) and the anonymous request carries no X-User-Id, so the restored X-Org-Id is refused, not served. Never fails OPEN. The availability cost is bounded to COLD caches: the edge key cache is stale-on-error (a warm cache keeps validating through a transient JWKS outage), so only a from-cold JWKS failure degrades to anonymous-403. The reserved admin org is NOT a parameter. It is the ISSUER's constant — IAM hardcodes it (store.IsSuperAdmin: `owner == "admin"`, and the reserved-org set beneath it) and authz publishes it as authz.AdminOrg — so a consumer-side knob could only ever let cloud DISAGREE with the token contract it is reading. That was not hypothetical: this file's own test doc asserted "Hanzo pins it to 'hanzo'", which, had anyone set IAM_ADMIN_ORG that way, would have handed platform sudo to every member of the hanzo org while IAM considered none of them a SuperAdmin. Production never set it, so the default carried the truth by luck. A knob whose only reachable non-default setting is an estate-wide escalation is not configuration; it is a loaded footgun, and it is now gone.

func ScopeRateLimit ¶ added in v1.786.112

func ScopeRateLimit(m *metering.Client, gp *edge.Store) zip.Handler

ScopeRateLimit returns the per-scope rate-limit middleware. It caps an authenticated org from TWO config sources, most-restrictive-wins:

• commerce spend-alert RateLimitRpm (the plan-configured ceiling), and
• the /v1/gateway per-org OrgRPM (gp), the runtime-mutable operator override.

It is a no-op passthrough only when BOTH are absent (no commerce AND no policy store), so an unwired deployment is never blocked — mirroring BillingGate.

func ServePlane ¶ added in v1.801.350

func ServePlane(name string, log luxlog.Logger) (func() error, error)

ServePlane binds the canonical socket for one app name and serves every op registered on the plane.

Serve calls it for each app this process mounts, AFTER Mount has run, so a resolvable socket always means "the app is up, with its ops live". An app that is up and answers 404 for an op is version skew — a different fact, and separately diagnosable.

It does not return until the socket ACCEPTS. Listening happens in a goroutine, so returning early made "the socket is bound" a race the caller could not see: Serve binds the plane before the app's own listener, and the host waits on that listener to call a child up — so a peer woken through the router could dial a socket that existed as a promise and not yet as a listener. Waiting here is what makes the ordering a guarantee instead of a coincidence.

func ServiceReleaserRegistered ¶ added in v1.801.7

func ServiceReleaserRegistered() bool

ServiceReleaserRegistered reports whether a first-party CR-rollout hook is installed (the paas control plane is co-resident). A caller uses it to know whether OnServiceRelease actually patches a CR or is a no-op, so it can be honest about which rollout path took effect.

func SetCompletionCeiling ¶ added in v1.801.408

func SetCompletionCeiling(f func(model string) int)

SetCompletionCeiling installs the per-model completion-ceiling lookup the prepaid gate reserves against. Called once at startup by the package that links the model catalog (apps/ai), so package cloud states WHAT it needs without importing where the answer lives — the same seam shape the AI module uses for SetContextWindowResolver.

func SetDraining ¶ added in v1.801.231

func SetDraining()

SetDraining marks the process draining (readiness → NotReady). Idempotent.

func SetRiskScorer ¶ added in v1.801.381

func SetRiskScorer(fn RiskScorer)

SetRiskScorer installs the ONE scorer. Called by the app that owns /v1/risk when its model and stores are ready. Installing nil uninstalls it, which is how a degraded scorer withdraws rather than answering badly.

func SetRollingCapReader ¶ added in v1.801.299

func SetRollingCapReader(f RollingCapReaderFunc)

SetRollingCapReader is the one EXPORTED setter here, and the deviation is forced: the four above are written directly by build.go/durable.go, which are inside this package, but the rolling cap is produced by clients/rollingcap — it imports clients/flags, which imports this package, so it can only ever live above that edge and needs a door. nil clears it (no cap installed).

func SetSwitchReader ¶ added in v1.801.218

func SetSwitchReader(f func(string) bool)

SetSwitchReader installs the platform-switch evaluator. clients/flags calls it once on mount; passing nil detaches it (used by tests).

func Severity ¶ added in v1.801.463

func Severity(action string) int

Severity ranks the vocabulary above, and it exists so that TWO judgements about one event compose into one answer: the severest of them stands.

It is here rather than at the one gate that fuses today because the ordering IS a property of the vocabulary — the constants are declared "most permissive first" and this makes that sentence executable, in the same file, so the prose and the code cannot drift into two orderings.

AN UNRECOGNISED ACTION RANKS BELOW ALLOW. It is not a milder verdict; it is a string this vocabulary does not contain, and letting one place anywhere in the order would let a typo win a fusion and become the outcome. Ranking it lowest means the judgement that IS recognised decides, and the fail policy — which is Decide's, not this function's — is what answers for the unrecognised one.

func SpendGate ¶ added in v1.801.242

func SpendGate(commerce CommerceClient) zip.Handler

SpendGate returns the balance-and-subscription gate serve.go mounts app-wide.

DEFAULT OFF, AND THAT IS A SEQUENCING DECISION, NOT TIMIDITY. A brand-new signup's wallet is $0 and there is NO automatic path that funds it: credit is an admin decision, granted deliberately through the admin surface, and the automatic starter grant that used to run as middleware here has been deleted outright rather than left switched off (an automatic path that mints money is a liability even when disabled, because disabled is one flag away from enabled).

So flipping this gate on 402s every new account from its first request. That is a real product decision — an honest paywall — and NOT one this flag should make silently as a side effect of the grant's removal. Until the paywall's add-credit state is the one a new user actually lands in, enforcing here trades a revenue leak for a signup that dead-ends. The gate therefore stays behind the kill switch, proven by tests, and is flipped as its own deliberate change.

Enforcement is read PER REQUEST from the platform switch an owner flips at admin.hanzo.ai, so it turns on and off within one flag-cache TTL — no redeploy, no CR edit. Switch reports false before the flag engine mounts, so an unmounted switch never enforces.

DECISION ORDER — a request is ADMITTED unless the one proven refusal fires:

1. enforcement OFF ........................ admit. Read FIRST, so a dark gate costs one atomic load and touches no authority.
2. not Billable ........................... admit. Reads, the pay path, and every non-metered route are never gated (see Billable / Reachable).
3. unvalidated principal .................. admit. An anonymous caller is the route's own 401 to make; a 402 is meaningless to someone not signed in, and the org on such a request is a forge anyway.
4. platform super-admin ................... admit. Platform sudo, including masquerade, is strictly tighter than any purchasable tier and never 402s.
5. subscribed OR funded ................... admit.
6. UNRESOLVABLE standing .................. posture (paywall_strict), logged WARN.
7. proven unpaid .......................... 402 with the actionable refusal.

FAIL POSTURE — argued, not inherited. The refusal in (7) requires PROOF: both authorities answered and both said no. An authority we could not reach yields Unknown, and by default an Unknown ADMITS. That is not "unpaid users get everything free whenever commerce hiccups" — it is "we never call a customer delinquent on evidence we do not have". The asymmetry decides it: refusing on an outage 402s every PAYING customer at once (a total product outage, irreversible), while admitting on an outage leaks access for the duration (bounded, recoverable, and separately capped — the subsystem meters still run their own fail-closed debit). Every fail-open admit logs at WARN with the reason, so a sustained leak pages rather than hides. When an owner wants the other trade, paywall_strict flips it live.

An unresolvable WALLET is an Unknown, not an admit: principal.WalletOf refuses an unresolvable org, and "we could not work out who pays" must refuse AS UNKNOWN and take the strict posture, never be silently waved through as if it were free.

func SubsystemOf ¶ added in v1.801.264

func SubsystemOf(path string) string

SubsystemOf resolves the subsystem serving path by longest declared prefix, or "" when nothing owns it (a non-/v1 path, or a route of a disabled subsystem).

func Switch ¶ added in v1.801.218

func Switch(key string) bool

Switch reports a platform switch's live value. It returns false before the flag engine mounts and when no engine is present (!cgo), which is the same dark default the engine itself falls back to — so an unmounted switch never enforces.

func Terminal ¶ added in v1.801.59

func Terminal(h func(*zip.Ctx) error) func(*zip.Ctx) error

Terminal wraps a handler so a returned *zip.HTTPError is written in-band (its status + the {status,code,error} JSON zip's default errorHandler would emit) and nil is returned, instead of propagating the error up the middleware chain.

It exists for routes mounted UNDER an outer error-flattening filter. The commerce embed installs one: mountCommerce (apps) registers ErrorHandlerJSON on an app.Group("/v1") whose middleware rewrites ANY error a downstream /v1 handler PROPAGATES into a hardcoded HTTP 500 — so a reject that returns zip.ErrUnauthorized (401) or zip.ErrBadRequest (400) up the chain surfaces to the client as 500. A subsystem mounted after commerce (git, sync, integrations, …) whose reject path must keep its real 4xx wraps its handler here: the status is written before the filter runs, so the filter's c.Next() sees nil and has nothing to flatten. A non-HTTPError (a genuine unexpected failure) passes through unchanged — those are 500s regardless. Compose with Handle: cloud.Terminal(cloud.Handle(s, fn)).

func TraceInprocEnabled ¶ added in v1.801.299

func TraceInprocEnabled() bool

TraceInprocEnabled reports whether the operator opted the in-process trace sink in. It is the ONE gate, read by the producer here (whether to install a provider at all when no wire endpoint is set) and by clients/o11y (whether to mount the sink) — no second source of truth. Fail-closed: unset ⇒ spans stay on the wire path.

func TracerProviderInstalled ¶ added in v1.801.299

func TracerProviderInstalled() bool

TracerProviderInstalled reports whether InstallTelemetry installed the OTel tracer provider in THIS process. It is the one fact the composition root needs in order to adopt the host provider into subsystems that emit their own spans (apps/install.go -> aiobject.AdoptHostTracerProvider). A value, not a callback: the same shape as TierReader/BalanceReader in ai.go, and for the same reason — importing github.com/hanzoai/ai/object here would put 1270 packages under every subsystem that imports cloud for Deps.

func TracingMiddleware ¶ added in v1.786.82

func TracingMiddleware() zip.Handler

TracingMiddleware emits ONE OpenTelemetry SERVER span per /v1/* request through the global (ZAP) tracer provider, so every api.hanzo.ai request lands in hanzoai/datastore over the ZAP wire alongside the log pipeline. It records the OTel HTTP semantic-convention attributes (method, route, status), sets the span status on error/5xx, and — critically — PROPAGATES the span context onto the request via SetContext so nested spans (agent.run, agent.step, the LLM chat client span in clients/aihttp.go) parent correctly under the request span. That makes a full agent trace a single tree: request → run → step → chat.

It is a plain zip.Handler wrapping c.Continue(), the framework's idiomatic middleware form (a plain request-scoped handler); no otelfiber shim is needed because zip already exposes method/path/status/context.

func TrustedProxy ¶ added in v1.801.381

func TrustedProxy(addr string) bool

TrustedProxy reports whether addr is one of our own forwarding hops — for a health report or a test, never as a gate. The gate is ClientIP, which applies the whole rule.

func UpstreamModel ¶ added in v1.801.231

func UpstreamModel(name string) bool

UpstreamModel reports whether name carries an upstream family name.

It matches the family as a WORD, not as a substring: a model id is split on its separators (vendor prefixes, tiers, sizes) and each word has its trailing version digits stripped, so "qwen3.5-397b", "fireworks/deepseek-v3" and "kimi-k2.6" all match while "zen5-coder" and "enso-flash" do not.

func Who ¶ added in v1.801.350

func Who(ctx context.Context) zip.Caller

Who reads the principal a plane op is acting for. A handler that needs authority refuses an empty org rather than treating it as permission.

func ZenModel ¶ added in v1.801.231

func ZenModel(name string) string

ZenModel returns the Hanzo name for a model: an upstream family name becomes DefaultModel, and a name that is already ours is returned unchanged (trimmed).

Mapping to the default rather than to a guessed tier is the honest answer. We are not claiming which enso tier a given upstream base corresponds to; we are saying the work runs on whatever this deployment runs unnamed work on, which is the same thing we would have told the caller had they named no model.

func ZipApp ¶ added in v1.801.299

func ZipApp(r Router) *zip.App

ZipApp recovers the concrete *zip.App behind a Router. It is what zip's TYPED registrars (zip.Get[In, Out] and friends) take, because a typed op is a route PLUS a registry entry — the one value the OpenAPI document, the MCP tool list and the CLI are all projected from — and that registry lives on the App.

This is the same deliberate hole as Fiber(), one level up, and it is safe for the same reason: registering an op is route registration, which scope has never bounded (it bounds middleware). nil means the Router is neither an App nor a scope, which no caller should paper over — a subsystem that cannot reach the registry must fail its mount rather than serve routes no projection knows.