cloud

type AIClient = types.AIClient

type Base struct {
	Log     luxlog.Logger
	KMS     KMSClient
	Bill    *ResourceMeter
	Brand   string
	Env     string
	Domain  string
	DataDir string
	// Durable is the deployment's HA-durability factory (nil ⇒ local-only). A
	// subsystem opening per-org SQLite passes it to NewOrgStore(WithDurable) to make
	// its stores survive rolling deploys/replicas.
	Durable *Durability
}

type BaseClient = types.BaseClient

type BrandInfo struct {
	// ID is the canonical brand key.
	ID string
	// IAMIssuer is the OIDC issuer (JWKS source) for this brand — the value the
	// JWT `iss` claim must equal and whose /v1/iam/.well-known/jwks signs tokens.
	IAMIssuer string
	// Domain is the brand's primary marketing/site domain (for response scoping
	// and base-URL derivation, e.g. api.<Domain>).
	Domain string
	// AltDomains are additional registrable domains that ALSO belong to this
	// brand, used ONLY for hostname→brand white-label detection (BrandForHostOK).
	// A brand's real serving surfaces span more than its marketing domain — the
	// cloud console runs on <brand>.cloud hosts (console.lux.cloud,
	// console.zoo.cloud), and a request Host there must brand as Lux/Zoo, never
	// fall through to Hanzo. Base-URL/issuer scoping still uses the primary Domain.
	AltDomains []string
}

type ChatRequest = types.ChatRequest

type ChatResponse = types.ChatResponse

type Claims = types.Claims

type CommerceClient = types.CommerceClient

type Config struct {
	// Enable lists subsystems to mount this run. Empty = all enabled.
	// Example: --enable=iam,base,kms,commerce,ai,gateway,o11y
	Enable []string

	// EnableStaged ADDITIVELY activates staged subsystems (stagedSubsystems) on top
	// of the default set, orthogonally to the Enable allowlist. It exists so a
	// deployment can run "every default subsystem PLUS iam" — the faithful prod +
	// staged-fold shape — WITHOUT collapsing Enable into a hand-enumerated allowlist
	// that silently drops a subsystem the day one is added. CLOUD_ENABLE_STAGED=iam
	// with an empty CLOUD_ENABLE = all-non-staged (the production default) + iam.
	// A staged name may equally be activated by naming it directly in Enable; this
	// is the additive path that does not disturb the non-staged default. One lever
	// per intent: Enable = "exactly this set", EnableStaged = "also turn these
	// staged ones on".
	EnableStaged []string

	// Replicas is the app-tier replica count the operator injects (CLOUD_REPLICAS,
	// mirroring the Deployment's spec.replicas). 0 = unset/unmanaged. It exists to
	// enforce ONE contract: embedded IAM (clients/iam) keeps its identity store as a
	// per-pod embedded SQLite file, so an iam-enabled cloud MUST run at a single
	// replica or each replica gets its OWN divergent identity store. Validate refuses
	// to boot iam-enabled above 1; the helm chart pins replicas=1 whenever "iam" is in
	// --enable. Pointing IAM at a shared external store lifts this.
	Replicas int

	// Brand is the white-label brand identifier.
	Brand string

	// Version is the API contract/build version emitted as the X-Api-Version
	// response header. Sourced from CLOUD_VERSION, else the link-time cloud.Version
	// default (see version.go).
	Version string

	// Env is the deployment environment (mainnet|testnet|devnet) per the 3-env
	// split. Billing fires in EVERY env — test/dev meter against their own
	// sandbox commerce/Square, never free — so Env is an attribution label, not
	// a gate. Empty when the operator has not set CLOUD_ENV.
	Env string

	// Domain is the deployment's primary public domain.
	Domain string

	// IAMIssuer is the JWKS issuer for JWT validation (usually iam.hanzo.ai).
	IAMIssuer string

	// AdminOrg is the IAM org slug whose members are SuperAdmins (IAM's
	// IsSuperAdmin: owner == AdminOrg). The in-binary identity sanitizer grants
	// admin authority — the c.IsAdmin() that gates /v1/admin/* writes, the
	// /v1/pricing/sync trigger, and the literal "admin" org bucket — ONLY to a
	// validated principal from this org, never to a raw header. Env IAM_ADMIN_ORG
	// (default "admin"), matching the gateway's admin-guard.
	AdminOrg string

	// JWKSURL is the JSON Web Key Set endpoint the identity sanitizer fetches IAM
	// signing keys from. Defaults to {IAMIssuer}/v1/iam/.well-known/jwks
	// (HIP-0111); override with CLOUD_JWKS_URL.
	JWKSURL string

	// KMSMasterKeyRef is the base64-encoded 32-byte KMS master key (KEK) the
	// embedded luxfi/kms store seals every secret's DEK under. The operator
	// injects it from a K8s Secret as CLOUD_KMS_MASTER_KEY_REF; cloud reads it
	// ONLY from env (never from the store it hosts — the bootstrap chicken-and-egg)
	// and never logs it. Empty ⇒ the KMS subsystem runs fail-closed (health-only).
	KMSMasterKeyRef string

	// KMSMPCAddr / KMSMPCVaultID configure the MPC threshold-signing backend for
	// KMS Sign. Both empty (the default) ⇒ Sign fails closed with a clear error;
	// signing is never fabricated. Set via CLOUD_KMS_MPC_ADDR / CLOUD_KMS_MPC_VAULT_ID.
	KMSMPCAddr    string
	KMSMPCVaultID string

	// DataDir is the on-disk data root.
	DataDir string

	// Role is the HA role of this process (CLOUD_ROLE): the single Writer that
	// owns the RWO stores (default) or a read-only Reader replica. Resolved and
	// validated in Serve; defaults to Writer so an unset variable is byte-identical
	// to today's single-pod deployment.
	Role role.Role

	// WriterURL is the base URL of the single writer (CLOUD_WRITER_URL, e.g.
	// http://cloud-writer.hanzo.svc:8000). A Reader forwards EVERY request here —
	// it opens no stores and is a transparent, always-ready edge that absorbs the
	// writer's rollout gap (see reader_proxy.go). Required when Role==Reader;
	// ignored by a Writer.
	WriterURL string

	// ReaderRetryBudget bounds how long a Reader retries a request the writer
	// could not yet accept (connection refused / no ready endpoint) during a
	// writer roll, before returning 502. Dial-only retry (the request never
	// reached the writer) keeps a non-idempotent POST safe. CLOUD_READER_RETRY_BUDGET
	// (Go duration, default 25s).
	ReaderRetryBudget time.Duration

	// WriterLease, when true (CLOUD_WRITER_LEASE), makes a Writer take an
	// exclusive fcntl lease on {DataDir}/.writer.lock BEFORE opening the RWO
	// stores and release it LAST at shutdown (after every store is closed). This
	// serializes a surge/overlap roll (RollingUpdate maxUnavailable:1 +
	// same-node podAffinity) so the new writer opens the exclusive-lock ZapDB/
	// audit stores only after the old one released them — never a double-open.
	// Default OFF, so an unset variable is byte-identical to today's Recreate
	// single-writer (which never overlaps and needs no lease). With per-pod RWO
	// PVCs (the sharded StatefulSet below) the lease is pod-local and never
	// contends across peers, so it stays OFF there — the shard router, not the
	// lease, is the cross-pod single-writer guarantee.
	WriterLease bool

	// ShardPeers is the CLOUD_PEERS membership list ("id@addr,id2@addr2") of the
	// horizontal-scale StatefulSet: the full, STABLE set of writer pods (each a
	// cloud-N ordinal at its headless per-pod DNS cloud-N.<svc>:8000). Every org is
	// pinned to exactly one owner pod by rendezvous hashing (ha.Owner over this set),
	// so each org's per-org SQLite files are written by ONE pod only; a request whose
	// org this pod does not own is forwarded to the owner (shardrouter.go). Empty or a
	// single entry ⇒ sharding OFF, byte-identical to the single-pod deployment. The
	// set is identical on every pod (static env), so all pods agree on every org's
	// owner — no split-brain dual-writer, no routing loop.
	ShardPeers string

	// ShardSelf is THIS pod's stable id — the StatefulSet ordinal name cloud-N, from
	// CLOUD_POD_NAME (or the downward-API POD_NAME). When sharding is on it MUST be one
	// of ShardPeers' ids (Validate refuses otherwise, so a misconfigured ordinal cannot
	// black-hole every request by forwarding it away with no shard of its own).
	ShardSelf string

	// ResearchDurable opts the per-org store into the HA object-store durability plane
	// (hydrate-on-open + fenced ship to org-db, CLOUD_RESEARCH_DURABLE). It is OFF by
	// default so a deploy never begins fencing real tenant data on the object store's
	// conditional-PUT atomicity before that atomicity is validated against the deployed
	// SeaweedFS version (the takeover-fence staging gate). With it off the store runs
	// local-only per pod — still single-writer-per-org via the shard router (ha.Owner) —
	// so the DDL-drift-proof + evidence-preserving record layer is fully active; only the
	// cross-restart object-store snapshot/fence waits for the opt-in.
	ResearchDurable bool

	// ListenAddr is the public HTTP listener (default :8080).
	ListenAddr string

	// ZAPListenAddr is the ZAP-RPC listener (default :9653).
	ZAPListenAddr string

	// ZAPWebOrigins is the WebSocket Origin allowlist for the browser-facing
	// /zap ZAP plane (the SPA hosts that may open a ZAP-over-WS connection).
	// Empty == same-origin only. Set via CLOUD_ZAP_WEB_ORIGINS (comma-sep).
	ZAPWebOrigins []string

	// MarkdownDefaultPrefixes lists path prefixes whose successful JSON
	// responses default to markdown (zap-proto/md) when the caller expresses no
	// format preference — the agent-facing endpoints (e.g. /v1/code/, /v1/agents/).
	// A caller always keeps the override: ?format=json or Accept: application/json
	// forces JSON even here, and JSON stays the default everywhere else. Empty ==
	// JSON everywhere unless explicitly negotiated. Env CLOUD_MARKDOWN_DEFAULT_PREFIXES
	// (comma-separated). See middleware_markdown.go.
	MarkdownDefaultPrefixes []string

	// Edge policy (middleware_edge.go) — the "gateway role" cloud absorbs when it
	// serves the public api.hanzo.ai edge directly, no KrakenD hop.
	//
	// CORSOrigins is the browser-CORS allowlist for the /v1 edge. Each entry is an
	// exact origin ("https://hanzo.ai"), a bare host ("hanzo.ai"), or a host
	// wildcard ("*.hanzo.ai" = apex + any subdomain). EMPTY ⇒ CORS is OWNED
	// ELSEWHERE (the shared Traefik ingress `cors-allow-all` fronting api.hanzo.ai)
	// and cloud emits NO CORS headers — set CLOUD_CORS_ORIGINS only on a direct
	// DO-LB→cloud edge, so exactly one layer answers CORS (never both → duplicate
	// ACAO breaks the browser). Reads CLOUD_CORS_ORIGINS, then GATEWAY_CORS_ORIGINS
	// (shared with the gateway so both trust boundaries agree on one list).
	CORSOrigins []string

	// EdgeRateEnabled turns on the per-client-IP edge flood cap that runs BEFORE
	// identity (CLOUD_EDGE_RATELIMIT, default true — the gateway enforced this, so
	// dropping it silently would drop a protection). EdgeRatePerIP requests per
	// EdgeRateWindowSec seconds are allowed per public client IP (leftmost
	// X-Forwarded-For); in-cluster direct callers carry no XFF and are exempt.
	// Defaults 100/1s mirror the gateway service-tier client_max_rate (strategy:ip).
	EdgeRateEnabled   bool
	EdgeRatePerIP     int
	EdgeRateWindowSec int

	// HealthListenAddr is the health/metrics listener (default :9090).
	HealthListenAddr string

	// AdminListenAddr is the admin endpoint (default :8081, gated by IAM admin).
	AdminListenAddr string

	// ReadBufferSize is the fasthttp per-conn request-read buffer for the public
	// HTTP edge (zip/fiber), in bytes. fasthttp caps total request-header size at
	// this value and returns 431 (Request Header Fields Too Large) above it. The
	// framework default is 4 KiB — too small once a multi-domain SSO session (an
	// admin-guard Domain=.hanzo.ai cookie set on EVERY subdomain) pushes a
	// browser's request headers past ~4 KiB, 431-ing legitimate requests. This
	// raises the edge ceiling to a sane 32 KiB (nginx large_client_header_buffers
	// parity). Env GATEWAY_READ_BUFFER_SIZE (shared with the gateway edge so both
	// trust boundaries agree on ONE value); tunable down if the per-conn memory
	// budget (SCALE_STANDARD §8) demands it. Internal zip services keep the 4 KiB
	// framework default — only the browser-facing edge opts up.
	ReadBufferSize int

	// BodyLimit is the maximum request body the public HTTP edge (zip/fiber)
	// accepts, in bytes. The framework default is 4 MiB — which silently caps the
	// CONTEXT WINDOW: a chat request carries its whole prompt in the body, and at
	// ~4.3 bytes/token a 1M-token prompt is ~4.3 MB. So the 1M-context models we
	// route to (deepseek-v4-pro; anything glm-5.2 overflows into past its 262,144
	// cap) could not actually be reached — fasthttp refused the body before any
	// handler ran, with the opaque 400 "Error when parsing request" that reads
	// like a malformed payload rather than a size cap. 16 MiB gives 1M tokens
	// real headroom (~3.7x) without inviting a memory-exhaustion vector: the edge
	// is authenticated + rate-limited, and fasthttp streams rather than buffering
	// per-conn. Env GATEWAY_BODY_LIMIT.
	BodyLimit int

	// SitesApex is the zone whose subdomains are PUBLIC published-site hosts
	// (`<slug>.<apex>`, default hanzo.app). The site host-router (clients/sites)
	// serves the root path space for these hosts from OUR S3, ahead of the API
	// pipeline, so a published site is a public artifact — never an org API call.
	// Env CLOUD_SITES_APEX.
	SitesApex string

	// SitesReserved lists subdomain labels under SitesApex that are NOT sites and
	// must fall through to the normal pipeline (real app/api hosts on the apex).
	// This is the reserved-host exclusion that stops a published site from
	// shadowing a real hanzo.app app. The empty label (apex) and "www" are always
	// reserved; these add to them. Env CLOUD_SITES_RESERVED (comma-separated).
	SitesReserved []string

	// SitesSelfDomains are OUR OWN registrable domains (hanzo.ai, hanzo.app, …).
	// The site edge serves a BOUND CUSTOM domain (a customer's own apex pointed at
	// this edge) from that project's S3 prefix — but only for hosts NOT at/under a
	// self domain, so the api/console path never does a per-request binding lookup
	// and a customer binding can never shadow a real Hanzo host. Defaults to the
	// apex plus the registrable domain of the deployment's own Domain (api.hanzo.ai
	// → hanzo.ai). Env CLOUD_SITES_SELF_DOMAINS (comma-separated) overrides.
	SitesSelfDomains []string

	// SitesFirstPartyApex is an internal SelfDomain (hanzo.ai) on which we serve a
	// small OPT-IN set of OUR OWN first-party sites (SitesFirstPartySites). Unlike
	// SitesApex — multi-tenant, sites-by-default with a reserved denylist — the brand
	// apex carries api/console/iam/kms/…, so it serves a site ONLY for an explicitly
	// allow-listed label; every other host falls through protected by default (no
	// denylist to keep complete). Env CLOUD_SITES_FIRSTPARTY_APEX (default hanzo.ai).
	SitesFirstPartyApex string
	// SitesFirstPartySites is the explicit allowlist of first-party site labels on
	// SitesFirstPartyApex (our internal pages: cd, flow, gallery). A user site never
	// lands here — users get <slug>.hanzo.app. Env CLOUD_SITES_FIRSTPARTY (comma-sep).
	SitesFirstPartySites []string
	// SitesFirstPartyOrg owns the first-party sites (hanzo). First-party host
	// resolution is PINNED to this org so a customer project can never shadow an
	// internal host (cd.hanzo.ai serves ONLY org hanzo's "cd"). Empty ⇒ first-party
	// sites are disabled (fail-closed). Env CLOUD_SITES_FIRSTPARTY_ORG (default hanzo).
	SitesFirstPartyOrg string

	// Endpoints for out-of-process subsystems (payments, vault). Empty
	// means the subsystem is disabled OR the deployment expects a default
	// service-discovery resolution.
	PaymentsZAPAddr string
	VaultZAPAddr    string

	// Billing gate (commerce metering) — the request-edge balance gate.
	//
	// CommerceHTTPURL is the commerce service base over HTTP (the metering
	// client speaks net/http, not ZAP). Empty disables the gate entirely.
	//
	// CommerceServiceToken is the admin-scoped commerce S2S token. It is a
	// SECRET sourced from a KMS-backed secret the operator injects as
	// COMMERCE_SERVICE_TOKEN — never hard-coded or read from disk here.
	//
	// BillingFailOpen flips the gate to allow-on-error. Default is
	// fail-closed (deny when balance can't be determined), matching the
	// gateway. Set only where availability outranks billing.
	CommerceHTTPURL      string
	CommerceServiceToken string
	BillingFailOpen      bool

	// PaywallEnforced turns on the subscription paywall (routers.Paywall): when true,
	// a gated /v1 product route from a validated org with NO active paid plan
	// (Pro/Plus/Max/Team/Enterprise, active or trialing) is refused with 402
	// subscription_required. Default FALSE — a DARK SHIP: the gate is a pure
	// passthrough until an owner sets PAYWALL_ENFORCED=true, so wiring it changes no
	// behavior. The sell/service surface (sign-in/billing/plans/models/health) is always
	// exempt so the gate can never block paying.
	PaywallEnforced bool

	// AI inference gateway. Two DISTINCT endpoints, two DISTINCT credentials by
	// concern (see build.go pickCompletionsClient / pickEmbedClient):
	//   - CHAT COMPLETIONS (deps.AI, a WRITE endpoint) — agents/guide/crm/content/
	//     sitegen/code-ask. Authenticated by the IAM M2M identity below, NEVER by a
	//     read-only publishable (pk-) key.
	//   - EMBEDDINGS (deps.Embed, a READ-ONLY endpoint) — code-index + KB. This is
	//     the ONLY consumer of AIAPIKey (the pk- key); read-only is exactly what a
	//     publishable key may do.
	//
	// AIBaseURL is the gateway /v1 root (CLOUD_AI_BASE_URL, default
	// https://api.hanzo.ai/v1); the client appends /chat/completions or /embeddings.
	//
	// AIAPIKey is the KMS-injected static gateway key (CLOUD_AI_API_KEY ←
	// cloud-ai-embed-key). It is a SECRET — never logged, printed, or read from disk
	// here. On the Hanzo deployment it is a read-only PUBLISHABLE (pk-) key: it feeds
	// deps.Embed (read-only, valid) and is REFUSED for deps.AI completions, which the
	// gateway would 403 ("Publishable keys can only access read-only endpoints"). A
	// completions-capable secret key (sk-/hk-) set here would instead drive both.
	//
	// AIDefaultModel is the served model an agent with no explicit model falls
	// back to (CLOUD_AI_DEFAULT_MODEL, default deepseek-v4-flash). Model routing
	// is the gateway's job; this is the ONLY cloud-side model default.
	//
	// AIFallbackModel is the reliable model the agent runner fails over to when
	// the agent's own model stays throttled (429/overloaded) after bounded retries
	// (CLOUD_AI_FALLBACK_MODEL, default "best" — the gateway's route-to-best
	// meta-model). It keeps an autonomous bot reply landing when the default flash
	// model is overloaded; the interactive chat path never uses it. Empty disables
	// failover (retry-only).
	AIBaseURL       string
	AIAPIKey        string
	AIDefaultModel  string
	AIFallbackModel string

	// AIAuthClientID / AIAuthClientSecret are the binary's OWN IAM service
	// identity (IAM_CLIENT_ID / IAM_CLIENT_SECRET). The completions client (deps.AI)
	// authenticates to the gateway with a client-credentials (M2M) token minted from
	// this identity and auto-refreshed — the durable no-static-key path, and the ONLY
	// completions credential when AIAPIKey is the read-only pk- embed key. On the
	// Hanzo deployment the identity resolves to admin/hanzo-cloud (gateway-balance-
	// exempt), so cloud's per-org ResourceMeter remains the single debit. The token
	// endpoint is derived from IAMIssuer ({issuer}/v1/iam/oauth/token). The secret is
	// KMS-injected and never logged.
	AIAuthClientID     string
	AIAuthClientSecret string

	// ZAP RPC endpoints for subsystems that are NOT enabled in this
	// process but are still needed by an enabled subsystem. Empty
	// means "no remote endpoint" — the client falls back to the
	// disabled stub which fails closed with a clear error.
	//
	// Convention: <subsystem>.<env>.<deployment>.svc:9653 — the same
	// inter-subsystem listener port the unified binary exposes. The
	// transport is hanzoai/zap, never JSON.
	IAMZAPAddr      string
	KMSZAPAddr      string
	BaseZAPAddr     string
	CommerceZAPAddr string
	AIZAPAddr       string
	O11yZAPAddr     string
	VFSZAPAddr      string
	MQZAPAddr       string

	// NodeID is this instance's stable identity within the control-plane quorum.
	// Env NODE_ID. Empty ⇒ unset.
	NodeID string

	// Peers is the control-plane peer set (the other nodes this instance would
	// form consensus with). Env PEERS (comma-separated). Empty ⇒ unset.
	Peers []string

	// ControlPlaneRole is this instance's control-plane role: "voter"
	// (participates in consensus) or "data" (data-plane only). Env ROLE.
	// Empty ⇒ unset. NAMED ControlPlaneRole (not Role) to avoid colliding with
	// the HA Role field above (role.Role, CLOUD_ROLE): #160 (writer/reader HA
	// split) and #163 (Stage-0 control plane) each added a `Role` to this struct
	// on separate branches, which broke the build on merge. This one is the inert
	// Stage-0 string — read but consumed by nothing until the engine is wired.
	ControlPlaneRole string

	// ControlPlaneQuorum is the number of voter nodes required to form a
	// control-plane quorum. Env CONTROL_PLANE_QUORUM. 0 ⇒ unset.
	ControlPlaneQuorum int
}

type Counter = types.Counter

type DBHandle = types.DBHandle

type Deps struct {
	// Logger is the canonical Hanzo logger (luxfi/log). Subsystems derive
	// scoped child loggers from this.
	Logger luxlog.Logger

	// Brand is the white-label brand identifier for this deployment.
	// Values: "hanzo", "lux", "zoo", "osage", "pars", or any customer brand.
	Brand string

	// Version is the API contract/build version emitted as the X-Api-Version
	// response header (see middleware.ProductionHeaders wiring in serve.go).
	Version string

	// Env is the deployment environment (mainnet|testnet|devnet). Subsystems
	// that meter usage stamp it for per-env attribution; it never gates or
	// bypasses billing (every env bills against its own commerce ledger).
	Env string

	// Domain is the deployment's primary domain (e.g. "api.hanzo.ai",
	// "api.osage.cloud"). Subsystems use this to scope URLs in responses.
	Domain string

	// IAMIssuer is the canonical OIDC issuer (JWKS source) for this brand,
	// resolved from Brand via the white-label registry unless pinned by the
	// operator. Subsystems validate JWT `iss` + signatures against
	// {IAMIssuer}/v1/iam/.well-known/jwks (HIP-0111). One issuer per deployment.
	IAMIssuer string

	// DataDir is the per-deployment data root. Per-org SQLite files
	// land at {DataDir}/orgs/{orgSlug}/{service}.db per HIP-0302.
	DataDir string

	// Durable is the per-deployment HA-durability factory an OrgStore wires
	// WithDurable: the shared ha election + vfs FencedStore over the SeaweedFS S3
	// gateway + per-org envelope Cipher. nil ⇒ local-only (no object store creds,
	// dev/single-node), and every OrgStore is exactly the pre-durability cache.
	Durable *Durability

	// AIDefaultModel is the served model a subsystem uses when a caller supplies
	// none (CLOUD_AI_DEFAULT_MODEL, default deepseek-v4-flash). It is the ONE
	// cloud-side model default, sourced from config so no subsystem hardcodes a
	// model id. The agents subsystem stores it on an agent created without an
	// explicit model, so a bot launched without a model still runs on a valid
	// catalog model. Model routing itself stays the gateway's job.
	AIDefaultModel string

	// AIFallbackModel is the reliable model the agent runner fails over to when an
	// agent's own model stays throttled after retries (CLOUD_AI_FALLBACK_MODEL,
	// default "best"). Only the autonomous agent/bot run path uses it; interactive
	// chat is untouched. Empty disables failover.
	AIFallbackModel string

	// Subsystem clients — populated by BuildDeps based on enabled subsystems.
	// Each is an interface with both in-process and ZAP-RPC implementations.
	IAM      IAMClient
	KMS      KMSClient
	Base     BaseClient
	Commerce CommerceClient
	// AI runs CHAT COMPLETIONS (a WRITE endpoint): agents, guide, crm, content,
	// sitegen, code /ask. It authenticates with the binary's IAM M2M identity — a
	// completions-capable credential — NEVER the read-only publishable (pk-) embed
	// key, which the gateway 403s on any write endpoint.
	AI AIClient
	// Embed runs EMBEDDINGS (a READ-ONLY endpoint): code-index + KB knowledge. This
	// is the ONLY consumer of the read-only publishable (pk-) key (CLOUD_AI_API_KEY),
	// the correct least-privilege credential for a read-only call. Split from AI so a
	// pk- embed key can never leak onto the completions path (the intermittent-403
	// bug). Falls back to the AI (M2M) resolution when no static embed key is set.
	Embed AIClient
	O11y  O11yClient
	VFS   VFSClient
	MQ    MQClient

	// Payments + Vault stay out-of-process (PCI scope isolation per
	// HIP-0106). These clients always resolve to ZAP-RPC implementations,
	// never in-process.
	Payments PaymentsClient
	Vault    VaultClient

	// Metering is the canonical commerce billing client used by the
	// request-edge BillingGate. It speaks net/http to commerce's billing API
	// (separate from the ZAP Commerce client above, which is for typed
	// inter-subsystem calls). Nil or not-Enabled() makes the gate a no-op.
	Metering *metering.Client

	// Audit is the tamper-evident, append-only audit trail Recorder (FedRAMP AU-*
	// / SOC 2 CC-*). Serve constructs it once, wires the AuditTrail middleware to
	// it, and hands it here so the /v1/admin/audit query + /v1/admin/audit/verify
	// endpoints read the SAME store the middleware writes. Nil makes the audit
	// middleware a no-op and the query endpoint fall back to the IAM proxy (an
	// unconfigured deployment is never blocked). See audit/ and audit_middleware.go.
	Audit *audit.Recorder

	// GatewayPolicy is the runtime-mutable edge-policy store (the /v1/gateway
	// config plane): CORS allowlist + pre-auth per-IP flood cap (platform scope)
	// and the authenticated per-org rate ceiling. BuildDeps constructs it once,
	// layered over the static env/flag defaults; the EdgeCORS/EdgeRateLimit
	// middleware read its PLATFORM policy live and ScopeRateLimit reads its
	// per-org OrgRPM, and the clients/gateway subsystem serves GET/PUT over the
	// SAME store. Never nil — New always returns a working (static-only on store
	// error) *Store, so the edge is never blocked. See clients/edge.
	GatewayPolicy *edge.Store
}

type Durability = org.Durability

type EmbedRequest = types.EmbedRequest

type GitImportReq struct {
	Org, Project, Repo string
	CloneURL           string // https://github.com/<owner>/<repo>.git (we construct it)
	Token              string // installation access token; env-only downstream, never argv/logs
	MirrorURL          string // outbound target to register; "" ⇒ don't register
}

type GitImporter interface {
	ImportRepo(ctx context.Context, req GitImportReq) error
	InboundSync(ctx context.Context, req GitInboundReq) (GitSyncResult, error)
	RepoStatus(ctx context.Context, org, project string, names []string) (map[string]GitRepoStatus, error)
}

type GitInboundReq struct {
	Org, Project, Repo string
	Branch             string // short branch name (refs/heads/<Branch>)
	CloneURL           string
	Token              string
	Origin             string // source host, e.g. "github.com"
}

type GitMirrorController interface {
	EnsureMirror(ctx context.Context, org, project, repo, url string, enabled bool) error
}

type GitPushEvent struct {
	Org      string
	Project  string
	Repo     string
	Branch   string
	Commit   string
	CloneURL string
}

type GitRepoStatus struct {
	Imported     bool  // a native repo exists for this name
	Conflict     bool  // a branch diverged on a prior inbound sync (native preserved)
	LastSyncedAt int64 // unix seconds of the last import/sync (0 = never)
}

type GitSyncResult struct {
	Applied  bool   // native advanced (fast-forward); a push.landed was emitted
	NoOp     bool   // already up to date (tip equal — the loop echo) or not imported
	Conflict bool   // native diverged; native was NOT overwritten (split-brain guard)
	Detail   string // human reason (conflict / skip)
	Before   string // native tip before (set on Applied)
	After    string // native tip after (set on Applied)
}

type IAMClient = types.IAMClient

type IntentRequest = types.IntentRequest

type IntentResponse = types.IntentResponse

type IntentStatus = types.IntentStatus

type IssueSink func(ctx context.Context, in IssueUpsert) (IssueUpsertResult, error)

type IssueUpsert struct {
	Org         string
	Project     string
	ProjectKey  string
	ProjectName string
	Repo        string
	ExtRef      string
	Kind        string
	Source      string
	Title       string
	Description string
	State       string // "open" | "closed"
	Assignee    string
	Labels      []string
}

type IssueUpsertResult struct {
	Created    bool
	Number     int
	Identifier string // KEY-<number>
}

type KMSClient = types.KMSClient

type LicenseEntitlement = types.LicenseEntitlement

type LifecycleEvent struct {
	Kind     LifecycleKind
	Org      string
	Project  string
	Repo     string
	Branch   string
	Before   string
	After    string
	Pusher   string
	DeployID string
	Detail   string
	Origin   string
}

type LifecycleKind string

type MQClient = types.MQClient

type MountFunc func(app *zip.App, deps Deps) error

type MountSpec struct {
	Name     string
	Mount    MountFunc
	Shutdown ShutdownFunc // optional; nil means the subsystem has nothing to tear down.

	// OwnsHealth marks a subsystem that serves its OWN GET /v1/<name>/health
	// (a real, fail-closed probe). Serve's generic liveness loop skips these so
	// its always-ok route never shadows the subsystem's real probe.
	OwnsHealth bool
}

type O11yClient = types.O11yClient

type Org = types.Org

type OrgConfig = types.OrgConfig

type OrgScopeResolver interface {
	// ProjectOwnership reports, for the project addressed by idOrSlug:
	//   mine  — org itself owns a project with this id/slug,
	//   other — some org OTHER than org owns a project with this id/slug.
	// A store failure is returned as err; the boundary then fails CLOSED (refuses
	// the claim) so a transient registry error can never let a cross-org claim
	// through.
	ProjectOwnership(ctx context.Context, org, idOrSlug string) (mine, other bool, err error)
}

type OrgStore[T io.Closer] struct {
	// contains filtered or unexported fields
}

type OrgStoreOption func(*orgStoreOpts)

type PaymentsClient = types.PaymentsClient

type ResourceMeter struct {
	// contains filtered or unexported fields
}

type Service[S any] struct {
	Base
	State S
}

type ServiceReleaseEvent struct {
	Service string
	Image   string
	SHA     string
}

type ShutdownFunc func(ctx context.Context) error

type Span = types.Span

type SyncEvent struct {
	Kind     string // sync kind, e.g. "git"
	Provider string // endpoint the event came from: "github" | "gitlab" | "hanzo-git"
	Org      string // tenant (from the signed installation / gateway identity)
	Locator  string // source repo locator (a clone URL, or "<org>/<repo>")
	Repo     string // short repo name (git)
	Branch   string
	Before   string
	After    string
	Actor    string // who made the upstream push — the loop guard compares it to the sync's own Actor
	Token    string // OPTIONAL short-lived credential the trigger already minted (git: installation token); never logged
	Manual   bool   // a manual /run or an initial sync reconcile (no specific push)
	Hop      int    // chained-propagation depth (bounded by the engine's hop limit)
}

type SyncFunc func(ctx context.Context, ev SyncEvent) (SyncResult, error)

type SyncResult struct {
	Ran     int // syncs that reconciled a change
	Skipped int // syncs resolved but skipped (loop guard / idempotent / direction off)
}

type Timing = types.Timing

type TokenValidator struct {
	// contains filtered or unexported fields
}

type User = types.User

type VFSClient = types.VFSClient

type VaultChargeRequest = types.VaultChargeRequest

type VaultChargeResponse = types.VaultChargeResponse

type VaultClient = types.VaultClient

type VerifiedIdentity struct {
	// Owner is the validated `owner` claim — the IAM org. This is the value the
	// SuperAdmin predicate compares against the reserved admin org.
	Owner string
	// User is the canonical user id (sub, then preferred_username, then name).
	User string
	// Username is the IAM username — the `name` half of `<owner>/<name>`.
	Username string
	// Email is the validated `email` claim, when present.
	Email string
	// IsAdmin is IAM's `isAdmin` bit: admin OF ONE'S OWN ORG. It is NOT the
	// SuperAdmin predicate — that is Owner == the reserved admin org, and
	// conflating the two is a privilege escalation. Reported so a caller can tell
	// an org admin from a plain member, never as the platform gate.
	IsAdmin bool
	// Orgs is the validated `orgs` membership-set claim — every org the subject
	// may act in (the HOME org first, then explicit team memberships), each with
	// its coarse role (owner | admin | member). It is the Slack-model tenancy set
	// a caller enumerates cross-org surfaces against (hanzo.team unions a user's
	// workspaces across it) with NO IAM round-trip. Empty on a token minted before
	// the claim shipped (iam < 1.31.34); a reader then falls back to the single
	// Owner org. Verified off the SAME signed token as Owner — never trusted raw.
	Orgs []model.OrgRef
	// Expiry is the token's own `exp`. A session built on this token must not
	// outlive it.
	Expiry time.Time
}