Merge milestone/v0.5-bearers-runtime into main (v0.5 Bearers Runtime feature milestone release)

v0.5 Bearers Runtime — 7 runtime REQs (REQ-033..039) shipped as feature.
8 modules promoted to runtime (MsgServer + simtest). cosmos-sdk v0.50.8 +
ibc-go v8.2.1 added (G-006 controlled exception). G-003 + locked-const
firewalls intact. 8 keeper packages ≥80% coverage. 5 GRILL decisions
ratified; 8 binding fixes landed; 5 P1+ flagged for v0.6+.

---ci---
project: oy
phase: 8
milestone: v0.5
status: complete
requirements:
  covered: [REQ-033, REQ-034, REQ-035, REQ-036, REQ-037, REQ-038, REQ-039]
  partial: []
---/ci---

x/services/types/expected_keepers.go

@@ -0,0 +1,120 @@
+package types
+
+// expected_keepers.go holds the Go INTERFACES for the cross-module keepers
+// x/services depends on at runtime (P5-01-01, REQ-037; G-003 firewall —
+// ibc-go expected-keepers convention; mirrors x/partner/types/expected_keepers.go
+// and x/hub/types/expected_keepers.go).
+//
+// The services runtime (REQ-037) depends on TWO cross-module keepers:
+//
+//  1. x/window (WindowKeeper) — the service-grant authority boundary. A
+//     service-grant opens a Window on the holder's behalf (A-307); the
+//     Window's status is the service's authority. The handler consults
+//     WindowKeeper.GetWindowStatus on EVERY service operation (A-552:
+//     window-grant-on-every-op — not just at registration); a Window that
+//     is not Active (Revoked / Expired / unknown) invalidates the op. This
+//     is the runtime echo of the v0.3 ServiceInfo.window-id by-ID-string
+//     field: the field stays a string (G-003), and the interface is the
+//     runtime validity boundary.
+//
+//  2. x/vault (VaultKeeper) — the VaultService (ServiceKind=Vault)
+//     provisioning shim. The MsgProvisionVault handler delegates the
+//     storage-quota provisioning to the x/vault keeper by-ID-string
+//     (A-553: VaultService references x/vault by ID via the shim — G-003).
+//     The v0.3 VaultService struct (types.go) named the x/vault collision
+//     conceptually (the ServiceKind "Vault" is a service kind, NOT a
+//     struct import); v0.5 wires the runtime provisioning via this
+//     interface (no struct import of x/vault/types — G-003 intact).
+//
+// Both dependencies are expressed as INTERFACES defined HERE (in
+// x/services/types), NOT as struct imports of x/window/types or
+// x/vault/types. The concrete keepers satisfy these interfaces
+// structurally (the P5 simtest wires stub implementations — G-003 test
+// exemption); the handler depends on the interface, preserving G-003's
+// intent (no cross-module struct coupling, no import cycles).
+//
+// Test-only cross-package imports (the G-003 test exemption) remain
+// exempt: the simtest imports x/services/keeper + defines stub types
+// that satisfy the interfaces (no production struct imports across
+// x/<module>/types).
+//
+// Lexicon note (REQ-012): "Window", "Vault", "service", "grant",
+// "provisioning" are all lexicon-clean. The holder identifier is
+// "reach-id" (NOT a banned financial-holder term; use Holder/Reach).
+
+// WindowStatus is the local redefinition of the x/window Window status
+// the services runtime cares about (G-003 — no struct import of
+// x/window/types; the status string crosses the interface boundary by
+// value). Only the Active status authorizes a service operation; any
+// other status (Revoked, Expired, unknown) invalidates the op (A-552).
+type WindowStatus string
+
+const (
+	// WindowStatusActive is the only status that authorizes a service
+	// operation. The handler consults WindowKeeper.GetWindowStatus on
+	// every op and REJECTS the op if the status is not Active (A-552).
+	WindowStatusActive WindowStatus = "Active"
+	// WindowStatusRevoked is a permanently-revoked Window (invalidates
+	// the service op — A-552).
+	WindowStatusRevoked WindowStatus = "Revoked"
+	// WindowStatusExpired is an expired Window (invalidates the service
+	// op — A-552: an op after the Window expired is a Window-violation).
+	WindowStatusExpired WindowStatus = "Expired"
+	// WindowStatusUnknown is the sentinel for a Window the keeper does
+	// not know about (treated as not-Active — the op is REJECTED).
+	WindowStatusUnknown WindowStatus = "Unknown"
+)
+
+// WindowKeeper is the expected-keeper interface for x/window (G-003). The
+// services handler consults it on EVERY service operation (A-552):
+//
+//   - RegisterService: the window-id on the new service must reference an
+//     Active Window BEFORE the service is created; a non-Active Window
+//     REJECTS the registration (the service is not created).
+//   - ActivateService / SuspendService / RevokeService: the window-id on
+//     the existing service must still be Active BEFORE the transition;
+//     a revoked/expired Window invalidates the op (the service stays in
+//     its pre-op status).
+//   - Per-kind handlers (IssueCareGrant, ActivateSIM, ProvisionVault,
+//     BindMailbox): the window-id on the service must still be Active
+//     BEFORE the per-kind op; a revoked/expired Window REJECTS the op
+//     (the per-kind state is NOT mutated).
+//
+// No struct import of x/window/types — the interface is the by-ID-string
+// boundary (G-003). The windowID is an opaque string (the by-ID-string
+// ref to an x/window Window; A-307).
+type WindowKeeper interface {
+	// GetWindowStatus reports the status of the named Window (by-ID-string)
+	// at the current block. The services handler consults this BEFORE
+	// every service op (A-552 — window-grant-on-every-op). Returns
+	// WindowStatusActive if the Window is live and authorizes ops;
+	// WindowStatusRevoked / WindowStatusExpired / WindowStatusUnknown if
+	// the Window is not authorizing. An error indicates the keeper could
+	// not answer (treated as not-Active — the op is REJECTED).
+	GetWindowStatus(windowID string) (WindowStatus, error)
+}
+
+// VaultKeeper is the expected-keeper interface for x/vault (G-003,
+// A-553). The VaultService (ServiceKind=Vault) handler calls it for:
+//
+//   - ProvisionVault: the MsgProvisionVault handler delegates the
+//     storage-quota-grain provisioning to the x/vault keeper by-ID-string
+//     (the vault-id on the VaultService is the by-ID-string ref to an
+//     x/vault Vault). A nil shim REJECTS the provisioning (the
+//     VaultService requires a real vault keeper — a nil shim is a wiring
+//     error, not a simtest skip path; the simtest wires a stub vault
+//     keeper, never nil).
+//
+// No struct import of x/vault/types — the interface is the by-ID-string
+// boundary (G-003, A-553). The serviceID is the by-ID-string ref to the
+// VaultService; the storage-quota-grain is the OY internal unit (by name
+// only — no x/bread import).
+type VaultKeeper interface {
+	// ProvisionVault records the storage-quota-grain provisioning for
+	// the named VaultService (by-ID-string). The MsgProvisionVault
+	// handler consults this AFTER the window-grant check (A-552) and
+	// BEFORE emitting the provisioning event. A non-nil error REJECTS
+	// the provisioning (the VaultService storage-quota-grain is NOT
+	// updated).
+	ProvisionVault(serviceID string, quotaGrain int64) error
+}

x/services/types/msg_services.go

@@ -0,0 +1,552 @@
+package types
+
+// msg_services.go holds the x/services Msg* types implementing sdk.Msg
+// (P5-01-01, REQ-037; G-006 controlled exception: types/ gains the
+// cosmos-sdk import for sdk.Msg — D-055; the invariant/lexicon tests in
+// *_test.go stay stdlib-only per G-024, isolated from this msg_*.go
+// file). Each Msg carries a ValidateBasic (stateless) and GetSigners.
+//
+// The eight Services Msg types drive the Care/SIM/Vault/Mail runtime
+// (REQ-037, A-551 per-kind typed dispatch — one Msg* per ServiceKind,
+// NOT a generic MsgInvokeService):
+//
+// Lifecycle (kind-agnostic):
+//   - MsgRegisterService: register a service (operator-reach-id valid;
+//     window-id must reference an Active Window — checked via the
+//     WindowKeeper shim at the handler; status=Pending).
+//   - MsgActivateService: Pending → Active (window-id must still be
+//     Active — A-552 window-grant-on-every-op).
+//   - MsgSuspendService: Active → Suspended.
+//   - MsgRevokeService: any → Revoked (terminal; revocation requires
+//     the Window grantor or a Watcher quorum — simtest wiring uses a
+//     nil WindowKeeper for the grantor check).
+//
+// Per-kind (typed dispatch — A-551):
+//   - MsgIssueCareGrant  (Care)  — issue a community-care grant.
+//   - MsgActivateSIM     (SIM)   — activate a connectivity SIM.
+//   - MsgProvisionVault  (Vault) — provision storage-quota-grain via
+//     the VaultKeeper shim (A-553: references x/vault by ID-string;
+//     G-003 — no struct import of x/vault/types).
+//   - MsgBindMailbox     (Mail)  — bind a messaging mailbox.
+//
+// All cross-module refs are by-ID-string (G-003): service-id is this
+// service's ID; operator-reach-id references an x/identity Reach by
+// ID-string; window-id references an x/window Window by ID-string
+// (A-307). GetSigners returns the signer reach-ids encoded as
+// sdk.AccAddress bytes. The reach-id is the lexicon-clean holder
+// identifier (G-003 — NOT a banned financial-holder term; use
+// Holder/Reach).
+
+import (
+	"fmt"
+
+	sdk "github.com/cosmos/cosmos-sdk/types"
+)
+
+// --- MsgRegisterService ------------------------------------------------------
+
+// MsgRegisterService registers a service (status=Pending). The handler
+// enforces the window-id must reference an Active Window via the
+// WindowKeeper shim (A-552). ValidateBasic is stateless: non-empty
+// service-id, non-empty operator-reach-id, non-empty window-id, a known
+// ServiceKind, non-empty name, non-empty signer.
+type MsgRegisterService struct {
+	ServiceID       string      `json:"service_id" yaml:"service_id"`
+	Kind            ServiceKind `json:"kind" yaml:"kind"`
+	OperatorReachID string      `json:"operator_reach_id" yaml:"operator_reach_id"`
+	Name            string      `json:"name" yaml:"name"`
+	WindowID        string      `json:"window_id" yaml:"window_id"`
+	Signer          string      `json:"signer" yaml:"signer"`
+}
+
+// Reset implements proto.Message (sdk.Msg = proto.Message).
+func (m *MsgRegisterService) Reset() { *m = MsgRegisterService{} }
+
+// String implements proto.Message.
+func (m *MsgRegisterService) String() string {
+	return fmt.Sprintf("MsgRegisterService{ServiceID:%s Kind:%s OperatorReachID:%s Name:%s WindowID:%s Signer:%s}",
+		m.ServiceID, m.Kind, m.OperatorReachID, m.Name, m.WindowID, m.Signer)
+}
+
+// ProtoMessage implements proto.Message.
+func (*MsgRegisterService) ProtoMessage() {}
+
+// ValidateBasic is the stateless validation: non-empty service-id, a
+// known ServiceKind, non-empty operator-reach-id, non-empty name,
+// non-empty window-id, non-empty signer. The handler enforces the
+// stateful Window-Active check via the WindowKeeper shim (A-552) +
+// idempotency (service-id must not already exist).
+func (m *MsgRegisterService) ValidateBasic() error {
+	if m.ServiceID == "" {
+		return fmt.Errorf("services: empty service-id")
+	}
+	if !knownServiceKind(m.Kind) {
+		return fmt.Errorf("services: unknown service kind %q", m.Kind)
+	}
+	if m.OperatorReachID == "" {
+		return fmt.Errorf("services: empty operator-reach-id")
+	}
+	if m.Name == "" {
+		return fmt.Errorf("services: empty name")
+	}
+	if m.WindowID == "" {
+		return fmt.Errorf("services: empty window-id")
+	}
+	if m.Signer == "" {
+		return fmt.Errorf("services: empty signer")
+	}
+	return nil
+}
+
+// GetSigners returns the signer's reach-id as sdk.AccAddress bytes.
+func (m *MsgRegisterService) GetSigners() []sdk.AccAddress {
+	return []sdk.AccAddress{[]byte(m.Signer)}
+}
+
+// --- MsgActivateService ------------------------------------------------------
+
+// MsgActivateService transitions a service Pending → Active. The
+// handler enforces the window-id on the existing service must still be
+// Active (A-552 window-grant-on-every-op). ValidateBasic is stateless:
+// non-empty service-id, non-empty signer.
+type MsgActivateService struct {
+	ServiceID string `json:"service_id" yaml:"service_id"`
+	Signer    string `json:"signer" yaml:"signer"`
+}
+
+// Reset implements proto.Message.
+func (m *MsgActivateService) Reset() { *m = MsgActivateService{} }
+
+// String implements proto.Message.
+func (m *MsgActivateService) String() string {
+	return fmt.Sprintf("MsgActivateService{ServiceID:%s Signer:%s}", m.ServiceID, m.Signer)
+}
+
+// ProtoMessage implements proto.Message.
+func (*MsgActivateService) ProtoMessage() {}
+
+// ValidateBasic is the stateless validation: non-empty service-id,
+// non-empty signer. The handler enforces the stateful source-status
+// check (must be Pending) and the window-grant Active check (A-552).
+func (m *MsgActivateService) ValidateBasic() error {
+	if m.ServiceID == "" {
+		return fmt.Errorf("services: empty service-id")
+	}
+	if m.Signer == "" {
+		return fmt.Errorf("services: empty signer")
+	}
+	return nil
+}
+
+// GetSigners returns the signer's reach-id as sdk.AccAddress bytes.
+func (m *MsgActivateService) GetSigners() []sdk.AccAddress {
+	return []sdk.AccAddress{[]byte(m.Signer)}
+}
+
+// --- MsgSuspendService -------------------------------------------------------
+
+// MsgSuspendService transitions a service Active → Suspended. The
+// handler enforces the window-id on the existing service must still be
+// Active (A-552 window-grant-on-every-op — a revoked Window
+// invalidates the transition). ValidateBasic is stateless: non-empty
+// service-id, non-empty signer.
+type MsgSuspendService struct {
+	ServiceID string `json:"service_id" yaml:"service_id"`
+	Signer    string `json:"signer" yaml:"signer"`
+}
+
+// Reset implements proto.Message.
+func (m *MsgSuspendService) Reset() { *m = MsgSuspendService{} }
+
+// String implements proto.Message.
+func (m *MsgSuspendService) String() string {
+	return fmt.Sprintf("MsgSuspendService{ServiceID:%s Signer:%s}", m.ServiceID, m.Signer)
+}
+
+// ProtoMessage implements proto.Message.
+func (*MsgSuspendService) ProtoMessage() {}
+
+// ValidateBasic is the stateless validation: non-empty service-id,
+// non-empty signer. The handler enforces the stateful source-status
+// check (must be Active) and the window-grant Active check (A-552).
+func (m *MsgSuspendService) ValidateBasic() error {
+	if m.ServiceID == "" {
+		return fmt.Errorf("services: empty service-id")
+	}
+	if m.Signer == "" {
+		return fmt.Errorf("services: empty signer")
+	}
+	return nil
+}
+
+// GetSigners returns the signer's reach-id as sdk.AccAddress bytes.
+func (m *MsgSuspendService) GetSigners() []sdk.AccAddress {
+	return []sdk.AccAddress{[]byte(m.Signer)}
+}
+
+// --- MsgRevokeService --------------------------------------------------------
+
+// MsgRevokeService transitions a service to Revoked (terminal). The
+// handler enforces the window-id on the existing service must still be
+// Active (A-552 window-grant-on-every-op — a revoked Window invalidates
+// the revocation too, mirroring the grantor-authorized revoke path).
+// Revocation in the simtest is grantor-authorized via the signer reach-
+// id; a Watcher quorum path is documented for the live chain (v0.6+).
+// ValidateBasic is stateless: non-empty service-id, non-empty signer.
+type MsgRevokeService struct {
+	ServiceID string `json:"service_id" yaml:"service_id"`
+	Signer    string `json:"signer" yaml:"signer"`
+}
+
+// Reset implements proto.Message.
+func (m *MsgRevokeService) Reset() { *m = MsgRevokeService{} }
+
+// String implements proto.Message.
+func (m *MsgRevokeService) String() string {
+	return fmt.Sprintf("MsgRevokeService{ServiceID:%s Signer:%s}", m.ServiceID, m.Signer)
+}
+
+// ProtoMessage implements proto.Message.
+func (*MsgRevokeService) ProtoMessage() {}
+
+// ValidateBasic is the stateless validation: non-empty service-id,
+// non-empty signer. The handler enforces the stateful source-status
+// check (must not already be Revoked — idempotent reject) and the
+// window-grant Active check (A-552).
+func (m *MsgRevokeService) ValidateBasic() error {
+	if m.ServiceID == "" {
+		return fmt.Errorf("services: empty service-id")
+	}
+	if m.Signer == "" {
+		return fmt.Errorf("services: empty signer")
+	}
+	return nil
+}
+
+// GetSigners returns the signer's reach-id as sdk.AccAddress bytes.
+func (m *MsgRevokeService) GetSigners() []sdk.AccAddress {
+	return []sdk.AccAddress{[]byte(m.Signer)}
+}
+
+// --- MsgIssueCareGrant (Care — A-551 typed dispatch) ------------------------
+
+// MsgIssueCareGrant issues a community-care grant against a Care service
+// (ServiceKind=Care — A-551 per-kind typed dispatch, NOT a generic
+// MsgInvokeService). The handler enforces the window-id on the existing
+// Care service must still be Active (A-552 window-grant-on-every-op).
+// ValidateBasic is stateless: non-empty service-id, non-empty
+// care-kind, non-empty grant-recipient-reach-id, non-empty signer.
+type MsgIssueCareGrant struct {
+	ServiceID             string `json:"service_id" yaml:"service_id"`
+	CareKind              string `json:"care_kind" yaml:"care_kind"`
+	GrantRecipientReachID string `json:"grant_recipient_reach_id" yaml:"grant_recipient_reach_id"`
+	Signer                string `json:"signer" yaml:"signer"`
+}
+
+// Reset implements proto.Message.
+func (m *MsgIssueCareGrant) Reset() { *m = MsgIssueCareGrant{} }
+
+// String implements proto.Message.
+func (m *MsgIssueCareGrant) String() string {
+	return fmt.Sprintf("MsgIssueCareGrant{ServiceID:%s CareKind:%s GrantRecipientReachID:%s Signer:%s}",
+		m.ServiceID, m.CareKind, m.GrantRecipientReachID, m.Signer)
+}
+
+// ProtoMessage implements proto.Message.
+func (*MsgIssueCareGrant) ProtoMessage() {}
+
+// ValidateBasic is the stateless validation: non-empty service-id,
+// non-empty care-kind, non-empty grant-recipient-reach-id, non-empty
+// signer. The handler enforces the stateful service-exists + kind=Care
+// + window-grant Active checks (A-552).
+func (m *MsgIssueCareGrant) ValidateBasic() error {
+	if m.ServiceID == "" {
+		return fmt.Errorf("services: empty service-id")
+	}
+	if m.CareKind == "" {
+		return fmt.Errorf("services: empty care-kind")
+	}
+	if m.GrantRecipientReachID == "" {
+		return fmt.Errorf("services: empty grant-recipient-reach-id")
+	}
+	if m.Signer == "" {
+		return fmt.Errorf("services: empty signer")
+	}
+	return nil
+}
+
+// GetSigners returns the signer's reach-id as sdk.AccAddress bytes.
+func (m *MsgIssueCareGrant) GetSigners() []sdk.AccAddress {
+	return []sdk.AccAddress{[]byte(m.Signer)}
+}
+
+// --- MsgActivateSIM (SIM — A-551 typed dispatch) ----------------------------
+
+// MsgActivateSIM activates a connectivity SIM against a SIM service
+// (ServiceKind=SIM — A-551 per-kind typed dispatch). The handler
+// enforces the window-id on the existing SIM service must still be
+// Active (A-552 window-grant-on-every-op). ValidateBasic is stateless:
+// non-empty service-id, non-empty carrier, non-empty
+// recipient-reach-id, non-empty signer.
+type MsgActivateSIM struct {
+	ServiceID        string `json:"service_id" yaml:"service_id"`
+	Carrier          string `json:"carrier" yaml:"carrier"`
+	RecipientReachID string `json:"recipient_reach_id" yaml:"recipient_reach_id"`
+	Signer           string `json:"signer" yaml:"signer"`
+}
+
+// Reset implements proto.Message.
+func (m *MsgActivateSIM) Reset() { *m = MsgActivateSIM{} }
+
+// String implements proto.Message.
+func (m *MsgActivateSIM) String() string {
+	return fmt.Sprintf("MsgActivateSIM{ServiceID:%s Carrier:%s RecipientReachID:%s Signer:%s}",
+		m.ServiceID, m.Carrier, m.RecipientReachID, m.Signer)
+}
+
+// ProtoMessage implements proto.Message.
+func (*MsgActivateSIM) ProtoMessage() {}
+
+// ValidateBasic is the stateless validation: non-empty service-id,
+// non-empty carrier, non-empty recipient-reach-id, non-empty signer.
+// The handler enforces the stateful service-exists + kind=SIM +
+// window-grant Active checks (A-552).
+func (m *MsgActivateSIM) ValidateBasic() error {
+	if m.ServiceID == "" {
+		return fmt.Errorf("services: empty service-id")
+	}
+	if m.Carrier == "" {
+		return fmt.Errorf("services: empty carrier")
+	}
+	if m.RecipientReachID == "" {
+		return fmt.Errorf("services: empty recipient-reach-id")
+	}
+	if m.Signer == "" {
+		return fmt.Errorf("services: empty signer")
+	}
+	return nil
+}
+
+// GetSigners returns the signer's reach-id as sdk.AccAddress bytes.
+func (m *MsgActivateSIM) GetSigners() []sdk.AccAddress {
+	return []sdk.AccAddress{[]byte(m.Signer)}
+}
+
+// --- MsgProvisionVault (Vault — A-551 typed dispatch, A-553 x/vault shim) ---
+
+// MsgProvisionVault provisions storage-quota-grain against a Vault
+// service (ServiceKind=Vault — A-551 per-kind typed dispatch; A-553:
+// references x/vault by ID via the VaultKeeper shim — G-003). The
+// handler enforces the window-id on the existing Vault service must
+// still be Active (A-552) and delegates the storage-quota-grain
+// provisioning to the VaultKeeper shim. ValidateBasic is stateless:
+// non-empty service-id, storage-quota-grain > 0, non-empty signer.
+type MsgProvisionVault struct {
+	ServiceID         string `json:"service_id" yaml:"service_id"`
+	StorageQuotaGrain int64  `json:"storage_quota_grain" yaml:"storage_quota_grain"`
+	Signer            string `json:"signer" yaml:"signer"`
+}
+
+// Reset implements proto.Message.
+func (m *MsgProvisionVault) Reset() { *m = MsgProvisionVault{} }
+
+// String implements proto.Message.
+func (m *MsgProvisionVault) String() string {
+	return fmt.Sprintf("MsgProvisionVault{ServiceID:%s StorageQuotaGrain:%d Signer:%s}",
+		m.ServiceID, m.StorageQuotaGrain, m.Signer)
+}
+
+// ProtoMessage implements proto.Message.
+func (*MsgProvisionVault) ProtoMessage() {}
+
+// ValidateBasic is the stateless validation: non-empty service-id,
+// storage-quota-grain > 0, non-empty signer. The handler enforces the
+// stateful service-exists + kind=Vault + window-grant Active checks
+// (A-552) and delegates to the VaultKeeper shim (A-553).
+func (m *MsgProvisionVault) ValidateBasic() error {
+	if m.ServiceID == "" {
+		return fmt.Errorf("services: empty service-id")
+	}
+	if m.StorageQuotaGrain <= 0 {
+		return fmt.Errorf("services: storage-quota-grain must be > 0")
+	}
+	if m.Signer == "" {
+		return fmt.Errorf("services: empty signer")
+	}
+	return nil
+}
+
+// GetSigners returns the signer's reach-id as sdk.AccAddress bytes.
+func (m *MsgProvisionVault) GetSigners() []sdk.AccAddress {
+	return []sdk.AccAddress{[]byte(m.Signer)}
+}
+
+// --- MsgBindMailbox (Mail — A-551 typed dispatch) ---------------------------
+
+// MsgBindMailbox binds a messaging mailbox against a Mail service
+// (ServiceKind=Mail — A-551 per-kind typed dispatch). The handler
+// enforces the window-id on the existing Mail service must still be
+// Active (A-552 window-grant-on-every-op). ValidateBasic is stateless:
+// non-empty service-id, non-empty mailbox-id, non-empty
+// holder-reach-id, non-empty signer.
+type MsgBindMailbox struct {
+	ServiceID     string `json:"service_id" yaml:"service_id"`
+	MailboxID     string `json:"mailbox_id" yaml:"mailbox_id"`
+	HolderReachID string `json:"holder_reach_id" yaml:"holder_reach_id"`
+	Signer        string `json:"signer" yaml:"signer"`
+}
+
+// Reset implements proto.Message.
+func (m *MsgBindMailbox) Reset() { *m = MsgBindMailbox{} }
+
+// String implements proto.Message.
+func (m *MsgBindMailbox) String() string {
+	return fmt.Sprintf("MsgBindMailbox{ServiceID:%s MailboxID:%s HolderReachID:%s Signer:%s}",
+		m.ServiceID, m.MailboxID, m.HolderReachID, m.Signer)
+}
+
+// ProtoMessage implements proto.Message.
+func (*MsgBindMailbox) ProtoMessage() {}
+
+// ValidateBasic is the stateless validation: non-empty service-id,
+// non-empty mailbox-id, non-empty holder-reach-id, non-empty signer.
+// The handler enforces the stateful service-exists + kind=Mail +
+// window-grant Active checks (A-552).
+func (m *MsgBindMailbox) ValidateBasic() error {
+	if m.ServiceID == "" {
+		return fmt.Errorf("services: empty service-id")
+	}
+	if m.MailboxID == "" {
+		return fmt.Errorf("services: empty mailbox-id")
+	}
+	if m.HolderReachID == "" {
+		return fmt.Errorf("services: empty holder-reach-id")
+	}
+	if m.Signer == "" {
+		return fmt.Errorf("services: empty signer")
+	}
+	return nil
+}
+
+// GetSigners returns the signer's reach-id as sdk.AccAddress bytes.
+func (m *MsgBindMailbox) GetSigners() []sdk.AccAddress {
+	return []sdk.AccAddress{[]byte(m.Signer)}
+}
+
+// --- MsgServer interface + Response types -----------------------------------
+
+// MsgServer is the services module's message server interface (one method
+// per Msg*). The keeper's msg_server.go implements this; module.go's
+// RegisterServices wires the implementation. This is the hand-rolled
+// equivalent of the protobuf-generated MsgServer interface (no codegen
+// per the skeleton's zero-codegen style).
+type MsgServer interface {
+	RegisterService(ctx interface{}, msg *MsgRegisterService) (*MsgRegisterServiceResponse, error)
+	ActivateService(ctx interface{}, msg *MsgActivateService) (*MsgActivateServiceResponse, error)
+	SuspendService(ctx interface{}, msg *MsgSuspendService) (*MsgSuspendServiceResponse, error)
+	RevokeService(ctx interface{}, msg *MsgRevokeService) (*MsgRevokeServiceResponse, error)
+	IssueCareGrant(ctx interface{}, msg *MsgIssueCareGrant) (*MsgIssueCareGrantResponse, error)
+	ActivateSIM(ctx interface{}, msg *MsgActivateSIM) (*MsgActivateSIMResponse, error)
+	ProvisionVault(ctx interface{}, msg *MsgProvisionVault) (*MsgProvisionVaultResponse, error)
+	BindMailbox(ctx interface{}, msg *MsgBindMailbox) (*MsgBindMailboxResponse, error)
+}
+
+// Response types (hand-rolled equivalents of the protobuf-generated
+// response wrappers; empty bodies — the response is the state mutation +
+// event).
+
+// MsgRegisterServiceResponse is the response to MsgRegisterService.
+type MsgRegisterServiceResponse struct{}
+
+// Reset implements proto.Message.
+func (m *MsgRegisterServiceResponse) Reset() { *m = MsgRegisterServiceResponse{} }
+
+// String implements proto.Message.
+func (m *MsgRegisterServiceResponse) String() string { return "MsgRegisterServiceResponse{}" }
+
+// ProtoMessage implements proto.Message.
+func (*MsgRegisterServiceResponse) ProtoMessage() {}
+
+// MsgActivateServiceResponse is the response to MsgActivateService.
+type MsgActivateServiceResponse struct{}
+
+// Reset implements proto.Message.
+func (m *MsgActivateServiceResponse) Reset() { *m = MsgActivateServiceResponse{} }
+
+// String implements proto.Message.
+func (m *MsgActivateServiceResponse) String() string { return "MsgActivateServiceResponse{}" }
+
+// ProtoMessage implements proto.Message.
+func (*MsgActivateServiceResponse) ProtoMessage() {}
+
+// MsgSuspendServiceResponse is the response to MsgSuspendService.
+type MsgSuspendServiceResponse struct{}
+
+// Reset implements proto.Message.
+func (m *MsgSuspendServiceResponse) Reset() { *m = MsgSuspendServiceResponse{} }
+
+// String implements proto.Message.
+func (m *MsgSuspendServiceResponse) String() string { return "MsgSuspendServiceResponse{}" }
+
+// ProtoMessage implements proto.Message.
+func (*MsgSuspendServiceResponse) ProtoMessage() {}
+
+// MsgRevokeServiceResponse is the response to MsgRevokeService.
+type MsgRevokeServiceResponse struct{}
+
+// Reset implements proto.Message.
+func (m *MsgRevokeServiceResponse) Reset() { *m = MsgRevokeServiceResponse{} }
+
+// String implements proto.Message.
+func (m *MsgRevokeServiceResponse) String() string { return "MsgRevokeServiceResponse{}" }
+
+// ProtoMessage implements proto.Message.
+func (*MsgRevokeServiceResponse) ProtoMessage() {}
+
+// MsgIssueCareGrantResponse is the response to MsgIssueCareGrant.
+type MsgIssueCareGrantResponse struct{}
+
+// Reset implements proto.Message.
+func (m *MsgIssueCareGrantResponse) Reset() { *m = MsgIssueCareGrantResponse{} }
+
+// String implements proto.Message.
+func (m *MsgIssueCareGrantResponse) String() string { return "MsgIssueCareGrantResponse{}" }
+
+// ProtoMessage implements proto.Message.
+func (*MsgIssueCareGrantResponse) ProtoMessage() {}
+
+// MsgActivateSIMResponse is the response to MsgActivateSIM.
+type MsgActivateSIMResponse struct{}
+
+// Reset implements proto.Message.
+func (m *MsgActivateSIMResponse) Reset() { *m = MsgActivateSIMResponse{} }
+
+// String implements proto.Message.
+func (m *MsgActivateSIMResponse) String() string { return "MsgActivateSIMResponse{}" }
+
+// ProtoMessage implements proto.Message.
+func (*MsgActivateSIMResponse) ProtoMessage() {}
+
+// MsgProvisionVaultResponse is the response to MsgProvisionVault.
+type MsgProvisionVaultResponse struct{}
+
+// Reset implements proto.Message.
+func (m *MsgProvisionVaultResponse) Reset() { *m = MsgProvisionVaultResponse{} }
+
+// String implements proto.Message.
+func (m *MsgProvisionVaultResponse) String() string { return "MsgProvisionVaultResponse{}" }
+
+// ProtoMessage implements proto.Message.
+func (*MsgProvisionVaultResponse) ProtoMessage() {}
+
+// MsgBindMailboxResponse is the response to MsgBindMailbox.
+type MsgBindMailboxResponse struct{}
+
+// Reset implements proto.Message.
+func (m *MsgBindMailboxResponse) Reset() { *m = MsgBindMailboxResponse{} }
+
+// String implements proto.Message.
+func (m *MsgBindMailboxResponse) String() string { return "MsgBindMailboxResponse{}" }
+
+// ProtoMessage implements proto.Message.
+func (*MsgBindMailboxResponse) ProtoMessage() {}

x/services/types/service_lifecycle.go

@@ -0,0 +1,69 @@
+package types
+
+// service_lifecycle.go holds the v0.5 runtime service lifecycle helpers
+// (P5-02-01, REQ-037). v0.3 typed the ServiceStatus enum (types.go);
+// v0.5 promotes it to runtime by adding the lifecycle transition gate
+// the keeper consults before mutating state. Mirrors
+// x/partner/types/anchor_credential.go (the v0.5 Anchor credential
+// lifecycle pattern — A-551 typed dispatch + A-552 window-grant-on-
+// every-op).
+//
+// Lifecycle (REQ-037, RESEARCH v0.5 §2.5):
+//
+//   RegisterService   → Pending   (window-id must be Active — A-552)
+//   ActivateService   → Pending → Active    (window-id still Active)
+//   SuspendService    → Active → Suspended (window-id still Active)
+//   RevokeService     → any → Revoked       (window-id still Active;
+//                       terminal)
+//
+// Invalid transitions are REJECTED by the handler (the simtest covers
+// each invalid transition). Revoked is terminal (no transition out of
+// Revoked — idempotent reject on a second Revoke). The lexicon-clean
+// holder identifier is "reach-id" (NOT a banned financial-holder term;
+// use Holder/Reach).
+
+// AllServiceStatuses returns all four ServiceStatus values in lifecycle
+// order (Pending, Active, Suspended, Revoked). Locked-const test (the
+// v0.3 types_test.go) asserts exactly 4 entries.
+func AllServiceStatuses() []ServiceStatus {
+	return []ServiceStatus{
+		ServicePending,
+		ServiceActive,
+		ServiceSuspended,
+		ServiceRevoked,
+	}
+}
+
+// IsTerminalServiceStatus reports whether the service status is terminal
+// (no further transitions permitted). Revoked is terminal.
+// Pending/Active/Suspended are non-terminal.
+func IsTerminalServiceStatus(s ServiceStatus) bool {
+	return s == ServiceRevoked
+}
+
+// ValidServiceTransition reports whether the from → to transition is
+// permitted by the REQ-037 lifecycle:
+//   - Pending → Active (ActivateService)
+//   - Active → Suspended (SuspendService)
+//   - Active → Revoked (RevokeService)
+//   - Suspended → Revoked (RevokeService)
+//   - Pending → Revoked (RevokeService — a Pending service may be
+//     revoked before activation)
+//
+// All other transitions are REJECTED. Revoked is terminal (no transition
+// out). The handler consults this helper before mutating state (the
+// window-grant Active check A-552 is a SEPARATE gate after this).
+func ValidServiceTransition(from, to ServiceStatus) bool {
+	switch from {
+	case ServicePending:
+		return to == ServiceActive || to == ServiceRevoked
+	case ServiceActive:
+		return to == ServiceSuspended || to == ServiceRevoked
+	case ServiceSuspended:
+		return to == ServiceRevoked
+	case ServiceRevoked:
+		return false // terminal
+	default:
+		return false // unknown source status
+	}
+}

x/services/types/types.go

@@ -169,6 +169,22 @@ func DefaultGenesisState() *GenesisState {
 	}
 }
 
+// Reset implements proto.Message (codec.JSONCodec.MustMarshalJSON /
+// MustUnmarshalJSON require proto.Message; the v0.5 runtime AppModule
+// calls these — D-055 G-006 controlled exception; the genesis fields +
+// ValidateGenesis logic are unchanged from v0.3, only the proto.Message
+// methods are added for the AppModule wiring).
+func (m *GenesisState) Reset() { *m = GenesisState{} }
+
+// String implements proto.Message.
+func (m *GenesisState) String() string {
+	return fmt.Sprintf("GenesisState{ServiceInfos:%d CareServices:%d SIMServices:%d VaultServices:%d MailServices:%d}",
+		len(m.ServiceInfos), len(m.CareServices), len(m.SIMServices), len(m.VaultServices), len(m.MailServices))
+}
+
+// ProtoMessage implements proto.Message.
+func (*GenesisState) ProtoMessage() {}
+
 // ValidateGenesis performs ID-uniqueness checks (A-212 upgrade from v0.1
 // no-op): rejects duplicate or empty service-ids in the registry, and unknown
 // ServiceKind / ServiceStatus values.