refactor(offerkind): declarative per-type integrity-profile registry

internal/offerkind is the single source of truth for what each ServiceOffer/Request type means — render/discovery shapes, price slots, capability flags, and a declarative IntegrityProfile per type. Routes x402 storefront copy + bazaar, the OpenAPI path shape, and the verifier's 402 integrity-metadata dispatch through it; centralizes price-slot detection in monetizeapi.Price.RawAndSlot(); adds a buy-side owner-pin nudge and a CRD-enum drift guard. Behavior-preserving.

Author: bussyjd

cmd/obol/dataset.go

@@ -34,6 +34,7 @@ import (
 
 	"github.com/ObolNetwork/obol-stack/internal/config"
 	"github.com/ObolNetwork/obol-stack/internal/dataset"
+	"github.com/ObolNetwork/obol-stack/internal/offerkind"
 	x402 "github.com/ObolNetwork/obol-stack/internal/x402"
 	"github.com/urfave/cli/v3"
 	x402types "github.com/x402-foundation/x402/go/types"
@@ -448,6 +449,15 @@ func buyDatasetCommand(cfg *config.Config) *cli.Command {
 				}
 				out = fmt.Sprintf("%s-v%d.jsonl", id, v)
 			}
+			// A dataset's integrity profile mandates signed-log content
+			// integrity, but the signed chain only proves it is self-consistent
+			// — not WHO signed it. Without an --owner pin, a seller that swapped
+			// its signing key still verifies, so surface the gap (the profile
+			// declares this check required for the guarantee to hold).
+			if offerkind.Resolve("dataset").Integrity.Content == offerkind.ContentSignedVersionLog &&
+				strings.TrimSpace(cmd.String("owner")) == "" {
+				u.Warnf("No --owner pin: the signed version log proves chain consistency but not the signer's identity. Pass --owner 0x<seller> for full content integrity.")
+			}
 			u.Infof("Fetching %s (version %v) → %s", id, orHead(cmd.Int("version")), out)
 			res, err := dataset.Fetch(ctx, dataset.FetchOptions{
 				BaseURL: base, ID: id, Version: cmd.Int("version"),

internal/monetizeapi/types.go

@@ -402,6 +402,27 @@ type ServiceOfferPriceTable struct {
 	PerMB string `json:"perMB,omitempty"`
 }
 
+// RawAndSlot returns the raw decimal price string and which price slot is
+// populated, in precedence order (perRequest > perMTok > perHour > perMB). It
+// is the single source of truth for price-slot detection, shared by the
+// catalog renderer (serviceoffercontroller) and the verifier's effectivePrice
+// (internal/x402). PerEpoch is intentionally not surfaced — no caller enforces
+// it yet, so including it would change behavior. An empty slot means no price.
+func (p ServiceOfferPriceTable) RawAndSlot() (raw, slot string) {
+	switch {
+	case p.PerRequest != "":
+		return p.PerRequest, "perRequest"
+	case p.PerMTok != "":
+		return p.PerMTok, "perMTok"
+	case p.PerHour != "":
+		return p.PerHour, "perHour"
+	case p.PerMB != "":
+		return p.PerMB, "perMB"
+	default:
+		return "", ""
+	}
+}
+
 type ServiceOfferRegistration struct {
 	// If true, register on ERC-8004 after routing is live.
 	// +kubebuilder:default=false

internal/offerkind/offerkind.go

@@ -0,0 +1,195 @@
+// Package offerkind is the single source of truth for what a ServiceOffer /
+// ServiceRequest "type" means: how it renders (storefront copy, bazaar and
+// OpenAPI discovery shapes), which price slot it uses, and — crucially —
+// which integrity checks apply to it.
+//
+// It replaces the type-collapse logic that was previously duplicated across
+// packages: internal/x402 (normalizeOfferType) and
+// internal/serviceoffercontroller (fallbackOfferType, openAPIPathsForOffer,
+// offerPriceRawAndUnit). Each of those re-implemented "given a spec.type,
+// what shape is this" with subtly different defaults. Centralizing here means
+// adding a 7th service type is a single table entry instead of an 8-file sweep.
+//
+// Design: this is a ZERO-DEPENDENCY leaf package (stdlib only). Call sites pass
+// the raw spec.type string (offer.Spec.Type), never a CRD struct, so both x402
+// and the controller can import it with no risk of an import cycle. The data
+// table mirrors how internal/bounty/registry.go makes task types data-driven.
+//
+// Integrity is kept strictly separate from pricing/upstream/rendering: the
+// IntegrityProfile declares only authenticity/identity/scope obligations, not
+// "is the price valid" (that is a pricing concern, not an integrity one).
+package offerkind
+
+// PaymentClass is the payment-integrity obligation for a type. Payment
+// verification itself is uniform x402 "exact"; the only real axis is whether a
+// payment proof is required at all (it always is, today) — method (card vs
+// crypto) is handled separately by the verifier, not here.
+type PaymentClass string
+
+const (
+	PaymentX402Exact PaymentClass = "x402-exact"
+	PaymentNone      PaymentClass = "none"
+)
+
+// ContentClass is the data-authenticity obligation: how a buyer proves the
+// bytes it received are the bytes the seller committed to.
+type ContentClass string
+
+const (
+	ContentNone             ContentClass = "none"
+	ContentSignedVersionLog ContentClass = "signed-version-log" // dataset / fine-tuning: owner-signed secp256k1 hash-chain (internal/dataset)
+	ContentBundleSHA256     ContentClass = "bundle-sha256"      // skill: controller-validated bundle hash+size
+)
+
+// IdentityClass is the caller-identity / membership obligation.
+type IdentityClass string
+
+const (
+	IdentityNone      IdentityClass = "none"
+	IdentityGroupAuth IdentityClass = "groupauth" // membership-gated via internal/research/groupauth
+)
+
+// ScopeClass is the entitlement-scope obligation layered on top of membership.
+type ScopeClass string
+
+const (
+	ScopeNone               ScopeClass = "none"
+	ScopeVersionEntitlement ScopeClass = "version-entitlement" // dataset: token entitled only up to a paid version
+)
+
+// IntegrityProfile declares the integrity checks a service type requires.
+// Consumed by the verifier and controller (to enforce) and by the buy-side
+// (to know what to verify before trusting a response).
+type IntegrityProfile struct {
+	Payment  PaymentClass
+	Content  ContentClass
+	Identity IdentityClass
+	Scope    ScopeClass
+}
+
+// Kind is the resolved capability + integrity descriptor for one spec.type.
+type Kind struct {
+	// Type is the canonical spec.type string this entry represents ("" for the
+	// unset default). Resolve(unknown) returns the http Kind, so its Type is
+	// "http", not the unknown input.
+	Type string
+
+	// PaymentCopy collapses the type into the three storefront-copy branches
+	// ("inference" | "agent" | "http"). Replaces x402.normalizeOfferType.
+	PaymentCopy string
+	// BazaarShape is the x402 bazaar discovery shape ("chat" | "generic").
+	BazaarShape string
+	// OpenAPIShape is the controller's OpenAPI path shape
+	// ("chat" | "multipart" | "generic").
+	OpenAPIShape string
+	// CatalogType is the display/catalog label (fallbackOfferType): the type
+	// string, or "http" when unset.
+	CatalogType string
+
+	// PriceUnits lists the price slot(s) a type conventionally uses, in
+	// precedence order. Informational/validation; the live price reader still
+	// keys off whichever Price.* field is populated.
+	PriceUnits []string
+
+	// SemanticInference mirrors monetizeapi.(*ServiceOffer).IsInference(): true
+	// for "" and "inference". Drives model-reconciliation gating and the
+	// OpenAPI empty-type edge (IsInference("")==true → chat shape).
+	SemanticInference bool
+	// ResolvesAgentRef: upstream comes from an Agent CR status, not spec.
+	ResolvesAgentRef bool
+	// RendersBundle: controller renders a skill bundle server.
+	RendersBundle bool
+	// OneShotPurchase: price is a total (e.g. perMB × size), not a rate.
+	OneShotPurchase bool
+
+	Integrity IntegrityProfile
+}
+
+// paymentOnly is the integrity profile for inference/http/agent: an x402
+// payment proof, nothing else.
+var paymentOnly = IntegrityProfile{
+	Payment:  PaymentX402Exact,
+	Content:  ContentNone,
+	Identity: IdentityNone,
+	Scope:    ScopeNone,
+}
+
+// kinds is the table. Keys are spec.type strings; "" is the unset default and
+// is deliberately distinct from "inference" because the legacy code treats the
+// empty type inconsistently — http-presentational (normalizeOfferType,
+// fallbackOfferType) yet inference-semantic (IsInference, openAPIPathsForOffer).
+// Encoding both faithfully keeps this refactor behavior-preserving.
+var kinds = map[string]Kind{
+	"": {
+		Type: "", PaymentCopy: "http", BazaarShape: "generic", OpenAPIShape: "chat",
+		CatalogType: "http", PriceUnits: []string{"perRequest", "perMTok"},
+		SemanticInference: true, Integrity: paymentOnly,
+	},
+	"inference": {
+		Type: "inference", PaymentCopy: "inference", BazaarShape: "chat", OpenAPIShape: "chat",
+		CatalogType: "inference", PriceUnits: []string{"perRequest", "perMTok"},
+		SemanticInference: true, Integrity: paymentOnly,
+	},
+	"http": {
+		Type: "http", PaymentCopy: "http", BazaarShape: "generic", OpenAPIShape: "generic",
+		CatalogType: "http", PriceUnits: []string{"perRequest"},
+		Integrity: paymentOnly,
+	},
+	"agent": {
+		Type: "agent", PaymentCopy: "agent", BazaarShape: "chat", OpenAPIShape: "chat",
+		CatalogType: "agent", PriceUnits: []string{"perRequest", "perMTok"},
+		ResolvesAgentRef: true, Integrity: paymentOnly,
+	},
+	"dataset": {
+		Type: "dataset", PaymentCopy: "http", BazaarShape: "generic", OpenAPIShape: "generic",
+		CatalogType: "dataset", PriceUnits: []string{"perMB"},
+		OneShotPurchase: true,
+		Integrity: IntegrityProfile{
+			Payment:  PaymentX402Exact,
+			Content:  ContentSignedVersionLog,
+			Identity: IdentityGroupAuth,
+			Scope:    ScopeVersionEntitlement,
+		},
+	},
+	"fine-tuning": {
+		Type: "fine-tuning", PaymentCopy: "http", BazaarShape: "generic", OpenAPIShape: "multipart",
+		CatalogType: "fine-tuning", PriceUnits: []string{"perHour"},
+		Integrity: IntegrityProfile{
+			Payment: PaymentX402Exact,
+			Content: ContentSignedVersionLog, // reuses the dataset signed-log primitives
+		},
+	},
+	"skill": {
+		Type: "skill", PaymentCopy: "http", BazaarShape: "generic", OpenAPIShape: "generic",
+		CatalogType: "skill", PriceUnits: []string{"perRequest"},
+		RendersBundle: true,
+		Integrity: IntegrityProfile{
+			Payment: PaymentX402Exact,
+			Content: ContentBundleSHA256,
+		},
+	},
+}
+
+// Resolve returns the Kind for a spec.type string. An unrecognized non-empty
+// type falls back to the http Kind (payment-only, generic shapes) — matching
+// the legacy normalizeOfferType / openAPIPathsForOffer defaults for unknown
+// types. The empty string resolves to its own dedicated entry.
+func Resolve(t string) Kind {
+	if k, ok := kinds[t]; ok {
+		return k
+	}
+	return kinds["http"]
+}
+
+// Types returns the canonical service-type strings the registry knows
+// (excluding the "" default), for drift checks against the CRD enum.
+func Types() []string {
+	out := make([]string, 0, len(kinds))
+	for k := range kinds {
+		if k == "" {
+			continue
+		}
+		out = append(out, k)
+	}
+	return out
+}

internal/offerkind/offerkind_test.go

@@ -0,0 +1,116 @@
+package offerkind
+
+import (
+	"os"
+	"strings"
+	"testing"
+)
+
+// TestResolve_CoversCRDEnum is the drift guard: every value in the
+// ServiceOffer.spec.type CRD enum (monetizeapi/types.go) must have a Kind.
+// Adding a 7th type to the enum without a table entry fails here, the same way
+// TestOpenClawVersionConsistency catches version drift.
+func TestResolve_CoversCRDEnum(t *testing.T) {
+	src, err := os.ReadFile("../monetizeapi/types.go")
+	if err != nil {
+		t.Fatalf("read types.go: %v", err)
+	}
+	var enumLine string
+	for _, ln := range strings.Split(string(src), "\n") {
+		if strings.Contains(ln, "+kubebuilder:validation:Enum=") && strings.Contains(ln, "inference") {
+			enumLine = ln
+			break
+		}
+	}
+	if enumLine == "" {
+		t.Fatal("could not find the ServiceOfferSpec.Type enum in monetizeapi/types.go")
+	}
+	_, rhs, _ := strings.Cut(enumLine, "Enum=")
+	values := strings.Split(strings.TrimSpace(rhs), ";")
+	if len(values) < 6 {
+		t.Fatalf("expected >=6 enum values, got %d from %q", len(values), rhs)
+	}
+	for _, v := range values {
+		v = strings.TrimSpace(v)
+		k := Resolve(v)
+		if k.Type != v {
+			t.Errorf("CRD enum value %q has no offerkind Kind (Resolve→Type %q); add it to kinds", v, k.Type)
+		}
+		if k.Integrity.Payment == "" {
+			t.Errorf("type %q has an empty Payment class", v)
+		}
+	}
+}
+
+// TestResolve_LegacyCollapseValues locks the exact collapse values the legacy
+// normalizeOfferType / openAPIPathsForOffer produced, so the rewire stays
+// behavior-preserving — including the deliberate "" split (generic bazaar but
+// chat openapi, because IsInference("")==true).
+func TestResolve_LegacyCollapseValues(t *testing.T) {
+	cases := []struct{ typ, paymentCopy, bazaar, openapi string }{
+		{"", "http", "generic", "chat"},
+		{"inference", "inference", "chat", "chat"},
+		{"http", "http", "generic", "generic"},
+		{"agent", "agent", "chat", "chat"},
+		{"dataset", "http", "generic", "generic"},
+		{"fine-tuning", "http", "generic", "multipart"},
+		{"skill", "http", "generic", "generic"},
+		{"totally-unknown", "http", "generic", "generic"},
+	}
+	for _, c := range cases {
+		k := Resolve(c.typ)
+		if k.PaymentCopy != c.paymentCopy {
+			t.Errorf("Resolve(%q).PaymentCopy = %q, want %q", c.typ, k.PaymentCopy, c.paymentCopy)
+		}
+		if k.BazaarShape != c.bazaar {
+			t.Errorf("Resolve(%q).BazaarShape = %q, want %q", c.typ, k.BazaarShape, c.bazaar)
+		}
+		if k.OpenAPIShape != c.openapi {
+			t.Errorf("Resolve(%q).OpenAPIShape = %q, want %q", c.typ, k.OpenAPIShape, c.openapi)
+		}
+	}
+}
+
+func TestResolve_IntegrityProfiles(t *testing.T) {
+	if got := Resolve("inference").Integrity; got != paymentOnly {
+		t.Errorf("inference integrity = %+v, want payment-only", got)
+	}
+	if got := Resolve("http").Integrity; got != paymentOnly {
+		t.Errorf("http integrity = %+v, want payment-only", got)
+	}
+	ds := Resolve("dataset").Integrity
+	if ds.Content != ContentSignedVersionLog || ds.Scope != ScopeVersionEntitlement || ds.Identity != IdentityGroupAuth {
+		t.Errorf("dataset integrity = %+v, want signed-log + version-entitlement + groupauth", ds)
+	}
+	if got := Resolve("skill").Integrity.Content; got != ContentBundleSHA256 {
+		t.Errorf("skill content = %q, want bundle-sha256", got)
+	}
+	if got := Resolve("fine-tuning").Integrity.Content; got != ContentSignedVersionLog {
+		t.Errorf("fine-tuning content = %q, want signed-version-log", got)
+	}
+}
+
+func TestResolve_SemanticInference(t *testing.T) {
+	for _, typ := range []string{"", "inference"} {
+		if !Resolve(typ).SemanticInference {
+			t.Errorf("Resolve(%q).SemanticInference = false, want true (matches IsInference)", typ)
+		}
+	}
+	for _, typ := range []string{"http", "agent", "dataset", "fine-tuning", "skill"} {
+		if Resolve(typ).SemanticInference {
+			t.Errorf("Resolve(%q).SemanticInference = true, want false", typ)
+		}
+	}
+}
+
+func TestResolve_CapabilityFlags(t *testing.T) {
+	if !Resolve("agent").ResolvesAgentRef {
+		t.Error("agent should resolve an Agent ref")
+	}
+	if !Resolve("skill").RendersBundle {
+		t.Error("skill should render a bundle")
+	}
+	if !Resolve("dataset").OneShotPurchase {
+		t.Error("dataset is a one-shot purchase (perMB→total)")
+	}
+}

internal/serviceoffercontroller/openapi.go

@@ -7,6 +7,7 @@ import (
 	"time"
 
 	"github.com/ObolNetwork/obol-stack/internal/monetizeapi"
+	"github.com/ObolNetwork/obol-stack/internal/offerkind"
 	"github.com/ObolNetwork/obol-stack/internal/schemas"
 )
 
@@ -201,8 +202,8 @@ func openAPIPathsForOffer(offer *monetizeapi.ServiceOffer) map[string]map[string
 	if offer == nil {
 		return nil
 	}
-	switch {
-	case offer.IsInference(), offer.IsAgent():
+	switch offerkind.Resolve(offer.Spec.Type).OpenAPIShape {
+	case "chat":
 		return map[string]map[string]any{
 			"/v1/chat/completions": {
 				"post": openAPIOperation(offer, openAPIOperationOptions{
@@ -219,7 +220,7 @@ func openAPIPathsForOffer(offer *monetizeapi.ServiceOffer) map[string]map[string
 				}),
 			},
 		}
-	case strings.EqualFold(offer.Spec.Type, "fine-tuning"):
+	case "multipart":
 		return map[string]map[string]any{
 			"": {
 				"post": openAPIOperation(offer, openAPIOperationOptions{