subsystems

Overview ¶

commerce.go mounts the hanzoai/commerce MODULE into the unified cloud binary (HIP-0106) — the un-fork of the old inlined clients/commerce tree. The module is a pure library (zero cloud imports); THIS adapter is the one place its embedded gin app is narrowed from cloud.Deps and wired to cloud's in-process seams (commerceinproc.SetHandler for S2S dispatch, PublishEmbedded for the entitlement client). Direction is one-way: cloud → commerce, no cycle.

WRAP, DON'T REWRITE. commerce.Embed runs the ENTIRE gin runtime (DB, per-org SQLite, KMS, hooks, cron) in-process, binds NO listener, and returns an http.Handler; the handler is attached verbatim at every prefix commerce owns.

PCI SCOPE. Commerce is a LIGHT ROUTER, NOT in PCI-DSS scope: tokens + intent IDs only, NEVER a PAN. PAN-touching paths call the out-of-process Payments / Vault (ZAP-RPC); when those clients are absent the payment handlers fail closed while tenant config + admin stay served — mountCommerce warns loudly at startup.

FAIL-SOFT. A broken Embed does NOT crash the binary: commerce degrades to a 503 on its own prefixes while every co-resident subsystem stays up.

Package subsystems is the composition root: the single, explicit list of which Hanzo cloud subsystems are linked into the binary AND the order they mount in.

Wire() returns []cloud.MountSpec in mount order (slice position == order). There is no init()-registry and no order-int: adding, removing, or reordering a subsystem is a one-line edit to Wire(), read top-to-bottom. cmd/cloud and cmd/hanzo both call Wire() and thread the slice into cloud.Serve — the set is defined ONCE, here.

(This package must NOT live in package cloud: the subsystems import cloud for Deps + Typed, so a root-package bundle would form an import cycle. As a sibling subpackage it composes them without one.)

HIP-0106: the unified cloud binary is the APPLICATION layer plus the embedded KMS secrets plane and the embedded IAM identity plane ("one Go binary embeds IAM + KMS + o11y"). The edge/infra tier (mcp, gateway, ingress-edge) runs as its own deployments for blast-radius isolation; several application folds (iam, base, commerce, captable, dataroom, sign, ingress) are STAGED — linked here but mounted only when the operator names them in CLOUD_ENABLE.

Ordering provenance: order-int ascending; ties in the exact order the pre-refactor init()-registry mounted them, captured empirically from origin/main @c504d2b (68 self-registering specs) and frozen by TestWireOrderMatchesFrozen (wire_test.go). ai (@150) and the hanzoai/o11y module wildcard (@70) are NOT in that dump: on their wave-2 tags (ai v1.805.2, o11y v1.5.12) they no longer self-register, so origin/main currently DROPS them (a latent regression this composition root fixes). They are wired back at their order-int slots — o11y-ext kept adjacent to the in-repo o11y read-plane (@69); ai as the last /v1/* catch-all before plugins (@900). Do not re-sort; edit positions deliberately.