@stackonward/cli 0.0.1 → 1.0.1

package/dist/resources/templates/go-backend/internal/integrations/onex/iam/errors.go

@@ -0,0 +1,102 @@
+package domain
+
+import "errors"
+
+// ═══════════════════════════════════════════════════════════════
+// IAM 授权内核 — 领域哨兵错误
+// ═══════════════════════════════════════════════════════════════
+//
+// 仅定义存在实际调用路径的哨兵错误（H5：不投机预留）；
+// 错误消息使用英文（C4）。调用方用 errors.Is 判定，errors.Unwrap 取根因。
+
+var (
+	// ErrInvalidResourceARN 资源 ARN 格式非法（段数 / 末段 type/id 切分不符合规范）。
+	ErrInvalidResourceARN = errors.New("iam: invalid resource ARN")
+	// ErrInvalidAction 动作格式非法（非 <domain>:<resource>:<verb> 三段或动词不在规范集合）。
+	ErrInvalidAction = errors.New("iam: invalid action")
+	// ErrPrincipalNotFound 认证身份未映射到活跃 IAM 主体（无主体 / 主体停用 / 已软删）。
+	ErrPrincipalNotFound = errors.New("iam: principal not found")
+	// ErrProductContextNotFound 产品注册表不存在指定产品。
+	ErrProductContextNotFound = errors.New("iam: product context not found")
+	// ErrProductContextInvalid 产品授权事实缺失、冲突或不完整。
+	ErrProductContextInvalid = errors.New("iam: product context invalid")
+	// ErrProductContextUnavailable 产品授权事实读取失败。
+	ErrProductContextUnavailable = errors.New("iam: product context unavailable")
+	// ErrCapabilityContextUnavailable 策略需要能力事实但请求未携带已解析快照。
+	ErrCapabilityContextUnavailable = errors.New("iam: capability context unavailable")
+	// ErrAdminAccessContextUnavailable 当前进程不能装配管理端授权上下文。
+	ErrAdminAccessContextUnavailable = errors.New("iam: admin access context unavailable")
+	// ErrAdminAccessContextInvalid 求值请求未使用权威工厂装配完整上下文。
+	ErrAdminAccessContextInvalid = errors.New("iam: admin access context invalid")
+	// ErrPolicyConditionInvalid 已发布策略包含无法执行的条件定义。
+	ErrPolicyConditionInvalid = errors.New("iam: policy condition invalid")
+	// ErrLastSuperAdmin 撤销绑定会导致平台不存在活跃的全局超级管理员。
+	ErrLastSuperAdmin = errors.New("iam: cannot revoke the last platform super admin role binding")
+)
+
+// IAM 控制台策略管理业务错误码（string ErrorCode，配合 pkg/apierror 构造 HTTP 响应，C5）。
+//
+// not-found 用 ResourceNotFound（404，由 apierror.NotFound 内置）；以下为本域特有的
+// 409（状态冲突 / 唯一冲突）与 422（业务规则）语义码，前端据码做差异化提示（设计 §8.2）。
+const (
+	// ErrCodePolicyCodeConflict 策略编码已存在（创建时唯一冲突，映射 409）。
+	ErrCodePolicyCodeConflict = "iam_policy_code_conflict"
+	// ErrCodePolicyInvalidTransition 策略状态机非法流转（如对终态再流转，映射 409）。
+	ErrCodePolicyInvalidTransition = "iam_policy_invalid_transition"
+	// ErrCodePolicyNotEditable 策略已超出可编辑窗口（仅 latest draft 可改语句，映射 422）。
+	ErrCodePolicyNotEditable = "iam_policy_not_editable"
+	// ErrCodePolicySystemManaged 系统策略只读，普通管理员不可编辑或流转（映射 422）。
+	ErrCodePolicySystemManaged = "iam_policy_system_managed"
+	// ErrCodePolicyForkSourceInvalid fork 来源不是系统策略（映射 422）。
+	ErrCodePolicyForkSourceInvalid = "iam_policy_fork_source_invalid"
+	// ErrCodePrincipalIdentityConflict 主体身份冲突（同一 identity_id 已绑定活跃主体，映射 409）。
+	ErrCodePrincipalIdentityConflict = "iam_principal_identity_conflict"
+	// ErrCodePrincipalTypeInvalid 主体类型非法（映射 422）。
+	ErrCodePrincipalTypeInvalid = "iam_principal_type_invalid"
+	// ErrCodeRoleCodeConflict 角色编码已存在（创建时唯一冲突，映射 409）。
+	ErrCodeRoleCodeConflict = "iam_role_code_conflict"
+	// ErrCodeRoleSystemManaged 系统内置角色只读，普通管理员不可编辑（映射 422）。
+	ErrCodeRoleSystemManaged = "iam_role_system_managed"
+	// ErrCodeBindingTargetInvalid 绑定目标非法（principal/role/group 三选一未恰好命中一个，映射 422）。
+	ErrCodeBindingTargetInvalid = "iam_binding_target_invalid"
+	// ErrCodeBindingScopeInvalid 绑定作用域非法（隔离维度 scope_value 为空，映射 422）。
+	ErrCodeBindingScopeInvalid = "iam_binding_scope_invalid"
+	// ErrCodeBindingConflict 绑定已存在（同 owner+scope 重复，映射 409）。
+	ErrCodeBindingConflict = "iam_binding_conflict"
+	// ErrCodeBindingProtected 绑定由专属权威服务管理，通用管理入口不可变更（映射 422）。
+	ErrCodeBindingProtected = "iam_binding_protected"
+	// ErrCodeLastSuperAdmin 不可解绑最后一个 platform_super 角色绑定（管理护栏，映射 422）。
+	ErrCodeLastSuperAdmin = "iam_last_super_admin"
+	// ErrCodeGroupCodeConflict 组编码已存在（创建时唯一冲突，映射 409）。
+	ErrCodeGroupCodeConflict = "iam_group_code_conflict"
+	// ErrCodeGroupScopeInvalid 组作用域非法（隔离维度 scope_value 为空或 global 带值，映射 422）。
+	ErrCodeGroupScopeInvalid = "iam_group_scope_invalid"
+	// ErrCodeGroupSystemManaged 系统内置组只读，普通管理员不可编辑或删除（映射 422）。
+	ErrCodeGroupSystemManaged = "iam_group_system_managed"
+	// ErrCodeGroupDeleteBlocked 用户组仍有活跃成员或策略绑定，不允许删除（映射 422）。
+	ErrCodeGroupDeleteBlocked = "iam_group_delete_blocked"
+	// ErrCodeGroupMemberConflict 组成员已存在（同 group+principal 重复，映射 409）。
+	ErrCodeGroupMemberConflict = "iam_group_member_conflict"
+	// ErrCodePageActionConflict 页面动作契约已存在（同 page_key+action_key 重复，映射 409）。
+	ErrCodePageActionConflict = "iam_page_action_conflict"
+	// ErrCodePageActionInvalid 页面动作契约字段非法（placement / risk / audit 取值不合法，映射 422）。
+	ErrCodePageActionInvalid = "iam_page_action_invalid"
+	// ErrCodeFieldRuleConflict 字段脱敏规则已存在（同 resource_type+field_key 重复，映射 409）。
+	ErrCodeFieldRuleConflict = "iam_field_rule_conflict"
+	// ErrCodeFieldRuleInvalid 字段脱敏规则字段非法（sensitivity / masking_strategy 取值不合法，映射 422）。
+	ErrCodeFieldRuleInvalid = "iam_field_rule_invalid"
+	// ErrCodeCredentialPrincipalInvalid 凭证归属主体非法（主体不存在 / 非 service_account 类型，映射 422）。
+	ErrCodeCredentialPrincipalInvalid = "iam_credential_principal_invalid" //nolint:gosec // G101: 错误码常量，非凭据
+	// ErrCodeServiceAccountDeleteBlocked 服务账号仍处于启用状态或存在依赖资源，不允许删除（映射 422）。
+	ErrCodeServiceAccountDeleteBlocked = "iam_service_account_delete_blocked"
+	// ErrCodeCredentialDeleteBlocked 凭证仍处于启用状态，不允许删除（映射 422）。
+	ErrCodeCredentialDeleteBlocked = "iam_credential_delete_blocked" //nolint:gosec // G101: 错误码常量，非凭据
+	// ErrCodeCredentialExpiresInvalid 凭证过期时间非法（早于当前时间，映射 422）。
+	ErrCodeCredentialExpiresInvalid = "iam_credential_expires_invalid" //nolint:gosec // G101: 错误码常量，非凭据
+	// ErrCodeCredentialRevoked 凭证已吊销，不可再吊销 / 轮换（终态，映射 422）。
+	ErrCodeCredentialRevoked = "iam_credential_revoked" //nolint:gosec // G101: 错误码常量，非凭据
+	// ErrCodeCredentialAuthenticationRejected 服务账号凭证认证失败（映射 401，不暴露具体失败原因）。
+	ErrCodeCredentialAuthenticationRejected = "iam_credential_authentication_rejected" //nolint:gosec // G101: 错误码常量，非凭据
+	// ErrCodeCredentialAuthorizationRejected 服务账号凭证授权失败（映射 403，不暴露具体失败原因）。
+	ErrCodeCredentialAuthorizationRejected = "iam_credential_authorization_rejected" //nolint:gosec // G101: 错误码常量，非凭据
+)

package/dist/resources/templates/go-backend/internal/integrations/onex/iam/principal_record.go

@@ -0,0 +1,21 @@
+package domain
+
+// PrincipalRecord IAM 主体解析结果（授权上下文所需的主体维度）。
+//
+// 是 Principal 实体投影的值对象：ID 为 IAM 主体主键（binding 表 principal_id 指向它），
+// IdentityID 才是关联的认证身份；二者语义不同不可混用（SH-I1）。隔离维度
+// （organization/merchant/tenant/agent）随主体携带，供求值器装配 PrincipalContext。
+type PrincipalRecord struct {
+	// IAM 主体主键（role/group/policy binding 的 principal_id 指向它）
+	ID int64
+	// 不可变主体公共引用。
+	PrincipalNo string
+	// 主体类型（见 enum.go PrincipalType，对应 condition principal_type）
+	PrincipalType string
+	// 关联认证身份 ID（human_user）。
+	IdentityID *int64
+	// 是否启用（停用主体所有授权立即失效）
+	IsActive bool
+	// 主体聚合版本。
+	Version int64
+}

package/dist/resources/templates/go-backend/internal/integrations/onex/iam/product_context.go

@@ -0,0 +1,486 @@
+package domain
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"sort"
+	"strings"
+	"time"
+)
+
+const productKindAttributeCode = "product_kind"
+
+// ProductAttributeFact 是 IAM 所需的单个产品属性事实。
+//
+// Value 为 nil 表示目录已知但当前没有生效值，以区分未知属性。
+type ProductAttributeFact struct {
+	// 属性编码
+	Code string
+	// 经产品所有者校验的 canonical JSON 值
+	Value json.RawMessage
+}
+
+// ProductCapabilityFact 产品授权所需的单个能力事实。
+type ProductCapabilityFact struct {
+	// 能力编码
+	Code string
+	// 是否在当前产品上下文中生效
+	Active bool
+}
+
+// ProductContextSnapshot 产品所有者投影给 IAM 的可信事实快照。
+//
+// Capabilities 非 nil 表示能力目录事实已经完整解析；空切片表示目录中没有能力事实。
+type ProductContextSnapshot struct {
+	// 产品编码
+	ProductCode string
+	// 产品形态，必须与 product_kind 属性一致
+	ProductKind string
+	// 产品生命周期状态
+	LifecycleStatus string
+	// 产品上下文单调写版本
+	ContextVersion int64
+	// 当前有效事实的 canonical 指纹
+	ContextFingerprint string
+	// 产品属性事实
+	Attributes []ProductAttributeFact
+	// 产品能力事实
+	Capabilities []ProductCapabilityFact
+	// 快照解析时刻
+	ResolvedAt time.Time
+	// 快照必须重新解析的最近边界
+	ExpiresAt *time.Time
+}
+
+// ProductAuthorizationContextReader 读取 IAM 所需的产品授权事实。
+//
+// 接口由 IAM 消费方定义；产品模块 Adapter 只投影该窄契约，不暴露产品仓储或数据库模型。
+type ProductAuthorizationContextReader interface {
+	ReadProductContextAt(ctx context.Context, productCode string, resolvedAt time.Time) (ProductContextSnapshot, error)
+}
+
+// ProductContext 是 IAM 求值器消费的不可变产品维度投影。
+type ProductContext struct {
+	// 产品编码
+	ProductCode string
+	// 产品形态
+	ProductKind string
+	// 生效能力编码集合
+	Capabilities []string
+	// 已解析的能力目录事实
+	CapabilityFacts []ProductCapabilityFact
+	// 已解析的属性目录事实
+	AttributeFacts []ProductAttributeFact
+	// 产品生命周期状态
+	LifecycleStatus string
+	// 产品上下文单调写版本
+	ContextVersion int64
+	// 当前有效事实的 canonical 指纹
+	ContextFingerprint string
+	// 快照解析时刻
+	ResolvedAt time.Time
+	// 快照必须重新解析的最近边界
+	ExpiresAt *time.Time
+}
+
+type productContextSnapshotKey struct{}
+
+// ResolveProductContextSnapshot 读取并规范化指定产品的可信授权事实。
+func ResolveProductContextSnapshot(
+	ctx context.Context,
+	reader ProductAuthorizationContextReader,
+	productCode string,
+	resolvedAt time.Time,
+) (ProductContextSnapshot, error) {
+	productCode = strings.TrimSpace(productCode)
+	if productCode == "" {
+		return ProductContextSnapshot{}, fmt.Errorf("%w: product code is required", ErrProductContextInvalid)
+	}
+
+	if reader == nil {
+		return ProductContextSnapshot{}, fmt.Errorf("%w: product context reader is not configured", ErrProductContextUnavailable)
+	}
+
+	snapshot, err := reader.ReadProductContextAt(ctx, productCode, resolvedAt)
+	if err != nil {
+		switch {
+		case errors.Is(err, ErrProductContextNotFound):
+			return ProductContextSnapshot{}, fmt.Errorf("resolve product context %q: %w", productCode, err)
+		case errors.Is(err, ErrProductContextInvalid), errors.Is(err, ErrProductContextUnavailable):
+			return ProductContextSnapshot{}, fmt.Errorf("resolve product context %q: %w", productCode, err)
+		default:
+			return ProductContextSnapshot{}, fmt.Errorf("%w: resolve product context %q: %v", ErrProductContextUnavailable, productCode, err)
+		}
+	}
+	normalized, err := snapshot.normalizedFor(productCode)
+	if err != nil {
+		return ProductContextSnapshot{}, err
+	}
+	if err := normalized.ValidateAt(resolvedAt); err != nil {
+		return ProductContextSnapshot{}, err
+	}
+	return normalized, nil
+}
+
+// ContextWithProductContextSnapshot 将已规范化快照绑定到当前请求，保证后续 IAM 装配校验并复用同一事实版本。
+func ContextWithProductContextSnapshot(ctx context.Context, snapshot ProductContextSnapshot) context.Context {
+	return context.WithValue(ctx, productContextSnapshotKey{}, snapshot.clone())
+}
+
+// ProductContextSnapshotFromContext 读取当前请求已校验的产品事实快照。
+func ProductContextSnapshotFromContext(ctx context.Context) (ProductContextSnapshot, bool) {
+	snapshot, ok := ctx.Value(productContextSnapshotKey{}).(ProductContextSnapshot)
+	if !ok {
+		return ProductContextSnapshot{}, false
+	}
+	return snapshot.clone(), true
+}
+
+// ActiveCapabilityCodes 返回去重且稳定排序的生效能力编码。
+func (s ProductContextSnapshot) ActiveCapabilityCodes() []string {
+	codes := make([]string, 0, len(s.Capabilities))
+	for i := range s.Capabilities {
+		if s.Capabilities[i].Active {
+			codes = append(codes, s.Capabilities[i].Code)
+		}
+	}
+	return codes
+}
+
+// ValidateAt 校验快照可在指定时刻进入请求上下文。
+func (s ProductContextSnapshot) ValidateAt(now time.Time) error {
+	if now.IsZero() {
+		return productContextInvalid(s.ProductCode, "validation time is required")
+	}
+	if s.ContextVersion <= 0 {
+		return productContextInvalid(s.ProductCode, "context version must be positive")
+	}
+	if !isLowerHexSHA256(s.ContextFingerprint) {
+		return productContextInvalid(s.ProductCode, "context fingerprint must be a lowercase SHA-256 value")
+	}
+	if s.ResolvedAt.IsZero() {
+		return productContextInvalid(s.ProductCode, "resolved time is required")
+	}
+	if s.ResolvedAt.After(now) {
+		return productContextInvalid(s.ProductCode, "resolved time must not be in the future")
+	}
+	if s.Attributes == nil {
+		return productContextInvalid(s.ProductCode, "attribute facts are unresolved")
+	}
+	if s.Capabilities == nil {
+		return productContextInvalid(s.ProductCode, "capability facts are unresolved")
+	}
+	if s.ExpiresAt != nil {
+		if !s.ExpiresAt.After(s.ResolvedAt) {
+			return productContextInvalid(s.ProductCode, "expiry must be after resolved time")
+		}
+		if !now.Before(*s.ExpiresAt) {
+			return productContextInvalid(s.ProductCode, "product context snapshot is expired")
+		}
+	}
+
+	productKind, err := s.productKind()
+	if err != nil {
+		return err
+	}
+	if s.ProductKind != "" && s.ProductKind != productKind {
+		return productContextInvalid(s.ProductCode, "product kind projection does not match product_kind attribute")
+	}
+	return nil
+}
+
+// AuthorizationContext 校验完整版本事实并投影为 IAM 产品上下文。
+func (s ProductContextSnapshot) AuthorizationContext(now time.Time) (ProductContext, error) {
+	if err := s.ValidateAt(now); err != nil {
+		return ProductContext{}, err
+	}
+	productKind, _ := s.productKind()
+
+	return ProductContext{
+		ProductCode:        s.ProductCode,
+		ProductKind:        productKind,
+		Capabilities:       s.ActiveCapabilityCodes(),
+		CapabilityFacts:    cloneCapabilityFacts(s.Capabilities),
+		AttributeFacts:     cloneAttributeFacts(s.Attributes),
+		LifecycleStatus:    s.LifecycleStatus,
+		ContextVersion:     s.ContextVersion,
+		ContextFingerprint: s.ContextFingerprint,
+		ResolvedAt:         s.ResolvedAt,
+		ExpiresAt:          cloneTime(s.ExpiresAt),
+	}, nil
+}
+
+// ValidateForWorkspace 验证 IAM 求值器收到的产品投影来自完整快照。
+func (c ProductContext) ValidateForWorkspace(productCode string, now time.Time) error {
+	productCode = strings.TrimSpace(productCode)
+	if productCode == "" {
+		if c.ProductCode != "" || c.ProductKind != "" || c.LifecycleStatus != "" ||
+			c.ContextVersion != 0 || c.ContextFingerprint != "" || !c.ResolvedAt.IsZero() ||
+			c.ExpiresAt != nil || c.AttributeFacts != nil || c.CapabilityFacts != nil || c.Capabilities != nil {
+			return productContextInvalid(c.ProductCode, "platform-global workspace must not carry product facts")
+		}
+		return nil
+	}
+	if c.ProductCode != productCode {
+		return productContextInvalid(productCode, "workspace product does not match product context")
+	}
+	if c.ProductKind == "" || c.LifecycleStatus == "" || c.ContextVersion <= 0 ||
+		!isLowerHexSHA256(c.ContextFingerprint) || c.ResolvedAt.IsZero() ||
+		c.AttributeFacts == nil || c.CapabilityFacts == nil || c.Capabilities == nil {
+		return productContextInvalid(productCode, "authorization product context is incomplete")
+	}
+	if c.LifecycleStatus != strings.TrimSpace(c.LifecycleStatus) {
+		return productContextInvalid(productCode, "authorization product context is not canonical")
+	}
+	if c.ResolvedAt.After(now) {
+		return productContextInvalid(productCode, "authorization product context resolved time is in the future")
+	}
+	if c.ExpiresAt != nil && !c.ExpiresAt.After(c.ResolvedAt) {
+		return productContextInvalid(productCode, "authorization product context expiry is invalid")
+	}
+	if c.ExpiresAt != nil && !now.Before(*c.ExpiresAt) {
+		return productContextInvalid(productCode, "authorization product context is expired")
+	}
+	if err := c.validateFacts(); err != nil {
+		return err
+	}
+	return nil
+}
+
+// HasCapability 判断产品上下文是否包含指定生效能力。
+func (c ProductContext) HasCapability(code string) bool {
+	code = strings.TrimSpace(code)
+	if code == "" || c.Capabilities == nil {
+		return false
+	}
+	index := sort.SearchStrings(c.Capabilities, code)
+	return index < len(c.Capabilities) && c.Capabilities[index] == code
+}
+
+// CapabilityState 返回能力是否生效以及该编码是否存在于目录事实。
+func (c ProductContext) CapabilityState(code string) (active bool, known bool) {
+	code = strings.TrimSpace(code)
+	if code == "" || c.CapabilityFacts == nil {
+		return false, false
+	}
+	index := sort.Search(len(c.CapabilityFacts), func(i int) bool {
+		return c.CapabilityFacts[i].Code >= code
+	})
+	if index >= len(c.CapabilityFacts) || c.CapabilityFacts[index].Code != code {
+		return false, false
+	}
+	return c.CapabilityFacts[index].Active, true
+}
+
+// AttributeFact 返回属性目录事实及当前是否存在生效值。
+func (c ProductContext) AttributeFact(code string) (json.RawMessage, bool, bool) {
+	code = strings.TrimSpace(code)
+	if code == "" || c.AttributeFacts == nil {
+		return nil, false, false
+	}
+	index := sort.Search(len(c.AttributeFacts), func(i int) bool {
+		return c.AttributeFacts[i].Code >= code
+	})
+	if index >= len(c.AttributeFacts) || c.AttributeFacts[index].Code != code {
+		return nil, false, false
+	}
+	if c.AttributeFacts[index].Value == nil {
+		return nil, true, false
+	}
+	return cloneJSON(c.AttributeFacts[index].Value), true, true
+}
+
+func (c ProductContext) validateFacts() error {
+	activeCodes := make([]string, 0, len(c.CapabilityFacts))
+	for i := range c.CapabilityFacts {
+		if c.CapabilityFacts[i].Code == "" || c.CapabilityFacts[i].Code != strings.TrimSpace(c.CapabilityFacts[i].Code) ||
+			(i > 0 && c.CapabilityFacts[i-1].Code >= c.CapabilityFacts[i].Code) {
+			return productContextInvalid(c.ProductCode, "capability facts are not canonical")
+		}
+		if c.CapabilityFacts[i].Active {
+			activeCodes = append(activeCodes, c.CapabilityFacts[i].Code)
+		}
+	}
+	if len(activeCodes) != len(c.Capabilities) {
+		return productContextInvalid(c.ProductCode, "active capability projection is inconsistent")
+	}
+	for i := range activeCodes {
+		if activeCodes[i] != c.Capabilities[i] {
+			return productContextInvalid(c.ProductCode, "active capability projection is inconsistent")
+		}
+	}
+
+	productKind := ""
+	for i := range c.AttributeFacts {
+		if c.AttributeFacts[i].Code == "" || c.AttributeFacts[i].Code != strings.TrimSpace(c.AttributeFacts[i].Code) ||
+			(i > 0 && c.AttributeFacts[i-1].Code >= c.AttributeFacts[i].Code) {
+			return productContextInvalid(c.ProductCode, "attribute facts are not canonical")
+		}
+		if c.AttributeFacts[i].Value != nil && !json.Valid(c.AttributeFacts[i].Value) {
+			return productContextInvalid(c.ProductCode, "attribute fact contains invalid JSON")
+		}
+		if c.AttributeFacts[i].Code != productKindAttributeCode || c.AttributeFacts[i].Value == nil {
+			continue
+		}
+		if err := json.Unmarshal(c.AttributeFacts[i].Value, &productKind); err != nil {
+			return productContextInvalid(c.ProductCode, "product_kind attribute must be a string")
+		}
+		productKind = strings.TrimSpace(productKind)
+	}
+	if productKind == "" || productKind != c.ProductKind {
+		return productContextInvalid(c.ProductCode, "product kind projection is inconsistent")
+	}
+	return nil
+}
+
+func (s ProductContextSnapshot) normalizedFor(productCode string) (ProductContextSnapshot, error) {
+	s.ProductCode = strings.TrimSpace(s.ProductCode)
+	s.ProductKind = strings.TrimSpace(s.ProductKind)
+	s.LifecycleStatus = strings.TrimSpace(s.LifecycleStatus)
+	s.ContextFingerprint = strings.TrimSpace(s.ContextFingerprint)
+	if s.ProductCode != productCode {
+		return ProductContextSnapshot{}, fmt.Errorf(
+			"%w: requested product %q but reader returned %q",
+			ErrProductContextInvalid,
+			productCode,
+			s.ProductCode,
+		)
+	}
+	if s.LifecycleStatus == "" {
+		return ProductContextSnapshot{}, fmt.Errorf("%w: product %q has no lifecycle status", ErrProductContextInvalid, productCode)
+	}
+	if s.Capabilities == nil {
+		return ProductContextSnapshot{}, fmt.Errorf("%w: product %q capabilities are unresolved", ErrProductContextInvalid, productCode)
+	}
+	if s.ContextVersion < 0 {
+		return ProductContextSnapshot{}, productContextInvalid(productCode, "context version must not be negative")
+	}
+	if s.ContextFingerprint != "" && !isLowerHexSHA256(s.ContextFingerprint) {
+		return ProductContextSnapshot{}, productContextInvalid(productCode, "context fingerprint must be a lowercase SHA-256 value")
+	}
+	if s.ExpiresAt != nil && !s.ResolvedAt.IsZero() && !s.ExpiresAt.After(s.ResolvedAt) {
+		return ProductContextSnapshot{}, productContextInvalid(productCode, "expiry must be after resolved time")
+	}
+
+	if s.Attributes != nil {
+		attributes := make([]ProductAttributeFact, len(s.Attributes))
+		seenAttributes := make(map[string]struct{}, len(s.Attributes))
+		for i := range s.Attributes {
+			code := strings.TrimSpace(s.Attributes[i].Code)
+			if code == "" {
+				return ProductContextSnapshot{}, productContextInvalid(productCode, "attribute code must not be empty")
+			}
+			if _, exists := seenAttributes[code]; exists {
+				return ProductContextSnapshot{}, productContextInvalid(productCode, "attribute facts contain duplicate codes")
+			}
+			seenAttributes[code] = struct{}{}
+			value := cloneJSON(s.Attributes[i].Value)
+			if value != nil && !json.Valid(value) {
+				return ProductContextSnapshot{}, productContextInvalid(productCode, "attribute fact contains invalid JSON")
+			}
+			attributes[i] = ProductAttributeFact{Code: code, Value: value}
+		}
+		sort.Slice(attributes, func(i, j int) bool { return attributes[i].Code < attributes[j].Code })
+		s.Attributes = attributes
+	}
+
+	capabilities := make([]ProductCapabilityFact, len(s.Capabilities))
+	seen := make(map[string]struct{}, len(s.Capabilities))
+	for i := range s.Capabilities {
+		code := strings.TrimSpace(s.Capabilities[i].Code)
+		if code == "" {
+			return ProductContextSnapshot{}, fmt.Errorf("%w: product %q contains an empty capability code", ErrProductContextInvalid, productCode)
+		}
+		if _, exists := seen[code]; exists {
+			return ProductContextSnapshot{}, fmt.Errorf("%w: product %q contains duplicate capability %q", ErrProductContextInvalid, productCode, code)
+		}
+		seen[code] = struct{}{}
+		capabilities[i] = ProductCapabilityFact{Code: code, Active: s.Capabilities[i].Active}
+	}
+	sort.Slice(capabilities, func(i, j int) bool {
+		return capabilities[i].Code < capabilities[j].Code
+	})
+	s.Capabilities = capabilities
+	s.ResolvedAt = s.ResolvedAt.UTC()
+	s.ExpiresAt = cloneTime(s.ExpiresAt)
+	return s, nil
+}
+
+func (s ProductContextSnapshot) clone() ProductContextSnapshot {
+	cloned := s
+	cloned.Attributes = cloneAttributeFacts(s.Attributes)
+	cloned.Capabilities = cloneCapabilityFacts(s.Capabilities)
+	cloned.ExpiresAt = cloneTime(s.ExpiresAt)
+	return cloned
+}
+
+func (s ProductContextSnapshot) productKind() (string, error) {
+	index := sort.Search(len(s.Attributes), func(i int) bool {
+		return s.Attributes[i].Code >= productKindAttributeCode
+	})
+	if index >= len(s.Attributes) || s.Attributes[index].Code != productKindAttributeCode || s.Attributes[index].Value == nil {
+		return "", productContextInvalid(s.ProductCode, "product_kind attribute is required")
+	}
+	var productKind string
+	if err := json.Unmarshal(s.Attributes[index].Value, &productKind); err != nil {
+		return "", productContextInvalid(s.ProductCode, "product_kind attribute must be a string")
+	}
+	productKind = strings.TrimSpace(productKind)
+	if productKind == "" {
+		return "", productContextInvalid(s.ProductCode, "product_kind attribute must not be empty")
+	}
+	return productKind, nil
+}
+
+func productContextInvalid(productCode string, reason string) error {
+	return fmt.Errorf("%w: product %q %s", ErrProductContextInvalid, productCode, reason)
+}
+
+func cloneAttributeFacts(facts []ProductAttributeFact) []ProductAttributeFact {
+	if facts == nil {
+		return nil
+	}
+	cloned := make([]ProductAttributeFact, len(facts))
+	for i := range facts {
+		cloned[i] = ProductAttributeFact{Code: facts[i].Code, Value: cloneJSON(facts[i].Value)}
+	}
+	return cloned
+}
+
+func cloneCapabilityFacts(facts []ProductCapabilityFact) []ProductCapabilityFact {
+	if facts == nil {
+		return nil
+	}
+	cloned := make([]ProductCapabilityFact, len(facts))
+	copy(cloned, facts)
+	return cloned
+}
+
+func cloneJSON(value json.RawMessage) json.RawMessage {
+	if value == nil {
+		return nil
+	}
+	return append(json.RawMessage(nil), value...)
+}
+
+func cloneTime(value *time.Time) *time.Time {
+	if value == nil {
+		return nil
+	}
+	cloned := value.UTC()
+	return &cloned
+}
+
+func isLowerHexSHA256(value string) bool {
+	if len(value) != 64 {
+		return false
+	}
+	for i := range value {
+		if (value[i] < '0' || value[i] > '9') && (value[i] < 'a' || value[i] > 'f') {
+			return false
+		}
+	}
+	return true
+}