From 79e0e5dc85f629b1b65a31b9685c99212c9e54f2 Mon Sep 17 00:00:00 2001
From: Joongi Kim <me@daybreaker.info>
Date: Mon, 27 Jul 2026 03:16:00 +0000
Subject: [PATCH] feat: core variant model, index schema, and selection
 algorithm

pkg/variant is pure (no registry/engine I/O): variant label and property
validation, image-label parsing, the variant index document
(schema-version 1), and the PEP 817-ported selection algorithm
(compatibility filter + namespace/feature/value priority ordering with
system-preference and lexicographic fallbacks).

One deviation from DESIGN.md as first written: property *values* accept
dots (^[a-z0-9_.]+$) since version-like values ("12.8") are the primary
use case; namespaces and features stay ^[a-z0-9_]+$. DESIGN.md is
amended in the base branch.

Also adds the Go module, Makefile, .gitignore, and a CI workflow
(gofmt check, vet, unit tests).

Claude-Session: https://claude.ai/code/session_01D383U8kkQkJc1yzyC5H5Nk
---
 .github/workflows/ci.yml     |  21 +++++
 .gitignore                   |   3 +
 Makefile                     |  15 ++++
 go.mod                       |   3 +
 pkg/variant/index.go         | 121 +++++++++++++++++++++++++
 pkg/variant/index_test.go    | 116 ++++++++++++++++++++++++
 pkg/variant/labels.go        |  94 +++++++++++++++++++
 pkg/variant/labels_test.go   | 125 ++++++++++++++++++++++++++
 pkg/variant/ordering.go      | 170 +++++++++++++++++++++++++++++++++++
 pkg/variant/ordering_test.go | 170 +++++++++++++++++++++++++++++++++++
 pkg/variant/property.go      | 132 +++++++++++++++++++++++++++
 11 files changed, 970 insertions(+)
 create mode 100644 .github/workflows/ci.yml
 create mode 100644 .gitignore
 create mode 100644 Makefile
 create mode 100644 go.mod
 create mode 100644 pkg/variant/index.go
 create mode 100644 pkg/variant/index_test.go
 create mode 100644 pkg/variant/labels.go
 create mode 100644 pkg/variant/labels_test.go
 create mode 100644 pkg/variant/ordering.go
 create mode 100644 pkg/variant/ordering_test.go
 create mode 100644 pkg/variant/property.go

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
new file mode 100644
index 0000000..4bfac90
--- /dev/null
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,21 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+      - name: gofmt
+        run: test -z "$(gofmt -l .)" || (gofmt -l . && exit 1)
+      - name: vet
+        run: go vet ./...
+      - name: unit tests
+        run: go test ./...
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..43b98c4
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,3 @@
+/bin/
+/dist/
+*.test
diff --git a/Makefile b/Makefile
new file mode 100644
index 0000000..863781a
--- /dev/null
+++ b/Makefile
@@ -0,0 +1,15 @@
+GO ?= go
+
+.PHONY: test vet fmt tidy
+
+test:
+	$(GO) test ./...
+
+vet:
+	$(GO) vet ./...
+
+fmt:
+	gofmt -w .
+
+tidy:
+	$(GO) mod tidy
diff --git a/go.mod b/go.mod
new file mode 100644
index 0000000..b6e76cd
--- /dev/null
+++ b/go.mod
@@ -0,0 +1,3 @@
+module github.com/achimnol/docker-variant
+
+go 1.26.4
diff --git a/pkg/variant/index.go b/pkg/variant/index.go
new file mode 100644
index 0000000..dfa2e26
--- /dev/null
+++ b/pkg/variant/index.go
@@ -0,0 +1,121 @@
+package variant
+
+import (
+	"encoding/json"
+	"fmt"
+)
+
+const (
+	// SchemaVersion of the variant index document this package produces.
+	SchemaVersion = "1"
+	// IndexArtifactType is the OCI artifactType (and layer media type) of the
+	// variant index artifact.
+	IndexArtifactType = "application/vnd.pep817.container-variants.v1+json"
+)
+
+// Entry describes one variant inside an Index.
+type Entry struct {
+	Properties Properties `json:"properties"`
+	// Tag is the variant tag the entry was generated from (informational).
+	Tag string `json:"tag,omitempty"`
+	// Digest of the manifest (or manifest list) the variant tag pointed to
+	// when the index was generated. Selection pulls by this digest.
+	Digest string `json:"digest,omitempty"`
+}
+
+// Priorities mirrors PEP 817's default-priorities: ordered preference lists
+// for namespaces, features within a namespace, and values within a feature.
+type Priorities struct {
+	Namespace []string                       `json:"namespace,omitempty"`
+	Feature   map[string][]string            `json:"feature,omitempty"`
+	Property  map[string]map[string][]string `json:"property,omitempty"`
+}
+
+// IsZero reports whether no priorities are set (used for omitzero).
+func (p Priorities) IsZero() bool {
+	return len(p.Namespace) == 0 && len(p.Feature) == 0 && len(p.Property) == 0
+}
+
+// Index is the per-(repository, base version) variant index — the container
+// analogue of PEP 817's {name}-{version}-variants.json.
+type Index struct {
+	SchemaVersion     string           `json:"schema-version"`
+	Repository        string           `json:"repository,omitempty"`
+	Version           string           `json:"version"`
+	DefaultPriorities Priorities       `json:"default-priorities,omitzero"`
+	Variants          map[string]Entry `json:"variants"`
+}
+
+// NewIndex returns an empty index for a repository and base version.
+func NewIndex(repository, version string) *Index {
+	return &Index{
+		SchemaVersion: SchemaVersion,
+		Repository:    repository,
+		Version:       version,
+		Variants:      map[string]Entry{},
+	}
+}
+
+// Upsert validates and inserts (or replaces) a variant entry.
+func (ix *Index) Upsert(label string, e Entry) error {
+	if err := ValidateLabel(label); err != nil {
+		return err
+	}
+	if e.Properties == nil {
+		e.Properties = Properties{}
+	}
+	if err := e.Properties.Validate(); err != nil {
+		return fmt.Errorf("variant %q: %w", label, err)
+	}
+	if label == NullLabel && e.Properties.Count() > 0 {
+		return fmt.Errorf("null variant must not declare properties")
+	}
+	ix.Variants[label] = e
+	return nil
+}
+
+// Validate checks the whole index document.
+func (ix *Index) Validate() error {
+	if ix.SchemaVersion != SchemaVersion {
+		return fmt.Errorf("unsupported schema-version %q (supported: %q)", ix.SchemaVersion, SchemaVersion)
+	}
+	if ix.Version == "" {
+		return fmt.Errorf("index has no version")
+	}
+	for label, e := range ix.Variants {
+		if err := ValidateLabel(label); err != nil {
+			return err
+		}
+		if err := e.Properties.Validate(); err != nil {
+			return fmt.Errorf("variant %q: %w", label, err)
+		}
+		if label == NullLabel && e.Properties.Count() > 0 {
+			return fmt.Errorf("null variant must not declare properties")
+		}
+	}
+	return nil
+}
+
+// ParseIndex unmarshals and validates an index document.
+func ParseIndex(data []byte) (*Index, error) {
+	var ix Index
+	if err := json.Unmarshal(data, &ix); err != nil {
+		return nil, fmt.Errorf("parsing variant index: %w", err)
+	}
+	if ix.Variants == nil {
+		ix.Variants = map[string]Entry{}
+	}
+	if err := ix.Validate(); err != nil {
+		return nil, err
+	}
+	return &ix, nil
+}
+
+// Marshal renders the index as indented JSON, ready for storage as the
+// artifact blob.
+func (ix *Index) Marshal() ([]byte, error) {
+	if err := ix.Validate(); err != nil {
+		return nil, err
+	}
+	return json.MarshalIndent(ix, "", "  ")
+}
diff --git a/pkg/variant/index_test.go b/pkg/variant/index_test.go
new file mode 100644
index 0000000..e36db19
--- /dev/null
+++ b/pkg/variant/index_test.go
@@ -0,0 +1,116 @@
+package variant
+
+import (
+	"encoding/json"
+	"testing"
+)
+
+func sampleIndex(t *testing.T) *Index {
+	t.Helper()
+	ix := NewIndex("registry.example.com/myimg", "2.1.0")
+	ix.DefaultPriorities = Priorities{
+		Namespace: []string{"nvidia", "x86_64"},
+		Feature:   map[string][]string{"nvidia": {"cuda_version_lower_bound"}},
+		Property: map[string]map[string][]string{
+			"nvidia": {"cuda_version_lower_bound": {"12.8", "12.0"}},
+		},
+	}
+	for label, e := range map[string]Entry{
+		"cu128": {
+			Properties: Properties{"nvidia": {"cuda_version_lower_bound": {"12.8"}}},
+			Tag:        "2.1.0-cu128",
+			Digest:     "sha256:aaa",
+		},
+		"null": {Properties: Properties{}, Tag: "2.1.0-null", Digest: "sha256:bbb"},
+	} {
+		if err := ix.Upsert(label, e); err != nil {
+			t.Fatalf("Upsert(%q): %v", label, err)
+		}
+	}
+	return ix
+}
+
+func TestIndexRoundTrip(t *testing.T) {
+	ix := sampleIndex(t)
+	data, err := ix.Marshal()
+	if err != nil {
+		t.Fatalf("Marshal: %v", err)
+	}
+	parsed, err := ParseIndex(data)
+	if err != nil {
+		t.Fatalf("ParseIndex: %v", err)
+	}
+	if parsed.Version != "2.1.0" || parsed.Repository != "registry.example.com/myimg" {
+		t.Errorf("round-trip lost identity: %+v", parsed)
+	}
+	if len(parsed.Variants) != 2 {
+		t.Errorf("round-trip lost variants: %v", parsed.Variants)
+	}
+	if got := parsed.Variants["cu128"].Properties.Get("nvidia", "cuda_version_lower_bound"); len(got) != 1 || got[0] != "12.8" {
+		t.Errorf("round-trip lost properties: %v", got)
+	}
+	if got := parsed.DefaultPriorities.Namespace; len(got) != 2 || got[0] != "nvidia" {
+		t.Errorf("round-trip lost priorities: %v", got)
+	}
+}
+
+func TestIndexJSONShape(t *testing.T) {
+	// The wire format is the contract of docs/DESIGN.md §3.2 — assert the
+	// exact key names.
+	data, err := sampleIndex(t).Marshal()
+	if err != nil {
+		t.Fatalf("Marshal: %v", err)
+	}
+	var raw map[string]json.RawMessage
+	if err := json.Unmarshal(data, &raw); err != nil {
+		t.Fatal(err)
+	}
+	for _, key := range []string{"schema-version", "repository", "version", "default-priorities", "variants"} {
+		if _, ok := raw[key]; !ok {
+			t.Errorf("marshaled index missing key %q in %s", key, data)
+		}
+	}
+	// An index without priorities omits the key entirely.
+	empty := NewIndex("r", "1.0")
+	data, err = empty.Marshal()
+	if err != nil {
+		t.Fatal(err)
+	}
+	raw = nil
+	if err := json.Unmarshal(data, &raw); err != nil {
+		t.Fatal(err)
+	}
+	if _, ok := raw["default-priorities"]; ok {
+		t.Errorf("empty priorities should be omitted: %s", data)
+	}
+}
+
+func TestIndexUpsertRejects(t *testing.T) {
+	ix := NewIndex("r", "1.0")
+	if err := ix.Upsert("variants", Entry{}); err == nil {
+		t.Error("Upsert(variants): want error (reserved)")
+	}
+	if err := ix.Upsert("BAD", Entry{}); err == nil {
+		t.Error("Upsert(BAD): want error")
+	}
+	if err := ix.Upsert("null", Entry{Properties: Properties{"nvidia": {"cuda": {"12.8"}}}}); err == nil {
+		t.Error("Upsert(null with properties): want error")
+	}
+	if err := ix.Upsert("cu128", Entry{Properties: Properties{"nvidia": {"cuda": {}}}}); err == nil {
+		t.Error("Upsert(empty value list): want error")
+	}
+}
+
+func TestParseIndexRejects(t *testing.T) {
+	cases := map[string]string{
+		"bad schema version": `{"schema-version": "99", "version": "1.0", "variants": {}}`,
+		"missing version":    `{"schema-version": "1", "variants": {}}`,
+		"invalid label":      `{"schema-version": "1", "version": "1.0", "variants": {"BAD": {"properties": {}}}}`,
+		"not json":           `nope`,
+	}
+	for name, doc := range cases {
+		if _, err := ParseIndex([]byte(doc)); err == nil {
+			t.Errorf("%s: want error, got nil", name)
+		}
+	}
+}
diff --git a/pkg/variant/labels.go b/pkg/variant/labels.go
new file mode 100644
index 0000000..5cbe458
--- /dev/null
+++ b/pkg/variant/labels.go
@@ -0,0 +1,94 @@
+package variant
+
+import (
+	"fmt"
+	"strings"
+)
+
+const (
+	// VariantLabelKey is the image config label carrying the variant label.
+	VariantLabelKey = "dev.pep817.variant-label"
+	// PropertyLabelPrefix prefixes image config labels carrying variant
+	// properties: dev.pep817.variant.<namespace>.<feature> = v1[,v2...]
+	PropertyLabelPrefix = "dev.pep817.variant."
+)
+
+// ParseImageLabels extracts the variant label and variant properties from an
+// image's config labels, per the schema in docs/DESIGN.md §2. It returns an
+// error if the variant label is missing or any key/value is malformed.
+// Non-variant labels are ignored.
+func ParseImageLabels(labels map[string]string) (string, Properties, error) {
+	label, ok := labels[VariantLabelKey]
+	if !ok {
+		return "", nil, fmt.Errorf("image has no %s label", VariantLabelKey)
+	}
+	if err := ValidateLabel(label); err != nil {
+		return "", nil, err
+	}
+	props := Properties{}
+	for key, value := range labels {
+		if !strings.HasPrefix(key, PropertyLabelPrefix) {
+			continue
+		}
+		nsFeature := strings.TrimPrefix(key, PropertyLabelPrefix)
+		ns, feature, found := strings.Cut(nsFeature, ".")
+		if !found {
+			return "", nil, fmt.Errorf("malformed property label key %q: want %s<namespace>.<feature>", key, PropertyLabelPrefix)
+		}
+		var values []string
+		for _, v := range strings.Split(value, ",") {
+			v = strings.TrimSpace(v)
+			if v != "" {
+				values = append(values, v)
+			}
+		}
+		if len(values) == 0 {
+			return "", nil, fmt.Errorf("property label %q has no values", key)
+		}
+		props.Add(ns, feature, values...)
+	}
+	if err := props.Validate(); err != nil {
+		return "", nil, err
+	}
+	if label == NullLabel && props.Count() > 0 {
+		return "", nil, fmt.Errorf("null variant must not declare properties, found %d", props.Count())
+	}
+	return label, props, nil
+}
+
+// IndexTag returns the tag addressing the variant index artifact for a base
+// version.
+func IndexTag(version string) string {
+	return version + "-variants"
+}
+
+// VariantTag returns the image tag for a (base version, label) pair.
+func VariantTag(version, label string) string {
+	return version + "-" + label
+}
+
+// BaseVersion strips the "-<label>" suffix from a variant tag, validating
+// that the tag actually ends with it.
+func BaseVersion(tag, label string) (string, error) {
+	suffix := "-" + label
+	version, found := strings.CutSuffix(tag, suffix)
+	if !found || version == "" {
+		return "", fmt.Errorf("tag %q does not end in %q: variant tags must be <base-version>-<label>", tag, suffix)
+	}
+	return version, nil
+}
+
+// MatchVariantTag reports whether tag names a variant of version, returning
+// the label. It is used when scanning a repository's tag list: it matches
+// "<version>-<label>" where label is syntactically valid and not the
+// reserved index suffix.
+func MatchVariantTag(tag, version string) (string, bool) {
+	label, found := strings.CutPrefix(tag, version+"-")
+	if !found {
+		return "", false
+	}
+	if ValidateLabel(label) != nil {
+		return "", false
+	}
+	return label, true
+}
diff --git a/pkg/variant/labels_test.go b/pkg/variant/labels_test.go
new file mode 100644
index 0000000..46ecfee
--- /dev/null
+++ b/pkg/variant/labels_test.go
@@ -0,0 +1,125 @@
+package variant
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestValidateLabel(t *testing.T) {
+	valid := []string{"cu128", "null", "cpu", "a", "x86_64.v3", "1.2_rc", strings.Repeat("a", 16)}
+	for _, label := range valid {
+		if err := ValidateLabel(label); err != nil {
+			t.Errorf("ValidateLabel(%q) = %v, want nil", label, err)
+		}
+	}
+	invalid := []string{"", "CU128", "cu-128", "cu 128", strings.Repeat("a", 17), "variants", "café"}
+	for _, label := range invalid {
+		if err := ValidateLabel(label); err == nil {
+			t.Errorf("ValidateLabel(%q) = nil, want error", label)
+		}
+	}
+}
+
+func TestParseImageLabels(t *testing.T) {
+	labels := map[string]string{
+		"dev.pep817.variant-label":                           "cu128",
+		"dev.pep817.variant.nvidia.cuda_version_lower_bound": "12.8",
+		"dev.pep817.variant.x86_64.level":                    "v3, v2",
+		"org.opencontainers.image.title":                     "unrelated",
+	}
+	label, props, err := ParseImageLabels(labels)
+	if err != nil {
+		t.Fatalf("ParseImageLabels: %v", err)
+	}
+	if label != "cu128" {
+		t.Errorf("label = %q, want cu128", label)
+	}
+	if got := props.Get("nvidia", "cuda_version_lower_bound"); len(got) != 1 || got[0] != "12.8" {
+		t.Errorf("nvidia property = %v, want [12.8]", got)
+	}
+	if got := props.Get("x86_64", "level"); len(got) != 2 || got[0] != "v3" || got[1] != "v2" {
+		t.Errorf("x86_64 level = %v, want [v3 v2] (comma-split, trimmed, ordered)", got)
+	}
+	if props.Count() != 2 {
+		t.Errorf("Count() = %d, want 2", props.Count())
+	}
+}
+
+func TestParseImageLabelsErrors(t *testing.T) {
+	cases := map[string]map[string]string{
+		"missing variant label": {
+			"dev.pep817.variant.nvidia.cuda_version_lower_bound": "12.8",
+		},
+		"invalid variant label": {
+			"dev.pep817.variant-label": "CU128",
+		},
+		"malformed property key (no feature)": {
+			"dev.pep817.variant-label":  "cu128",
+			"dev.pep817.variant.nvidia": "12.8",
+		},
+		"empty property value": {
+			"dev.pep817.variant-label":       "cu128",
+			"dev.pep817.variant.nvidia.cuda": " , ",
+		},
+		"invalid value chars": {
+			"dev.pep817.variant-label":       "cu128",
+			"dev.pep817.variant.nvidia.cuda": "12.8;drop",
+		},
+		"null variant with properties": {
+			"dev.pep817.variant-label":       "null",
+			"dev.pep817.variant.nvidia.cuda": "12.8",
+		},
+	}
+	for name, labels := range cases {
+		if _, _, err := ParseImageLabels(labels); err == nil {
+			t.Errorf("%s: want error, got nil", name)
+		}
+	}
+}
+
+func TestTagHelpers(t *testing.T) {
+	if got := IndexTag("2.1.0"); got != "2.1.0-variants" {
+		t.Errorf("IndexTag = %q", got)
+	}
+	if got := VariantTag("2.1.0", "cu128"); got != "2.1.0-cu128" {
+		t.Errorf("VariantTag = %q", got)
+	}
+	version, err := BaseVersion("2.1.0-cu128", "cu128")
+	if err != nil || version != "2.1.0" {
+		t.Errorf("BaseVersion = %q, %v", version, err)
+	}
+	// A base version containing dashes survives the round-trip.
+	version, err = BaseVersion("2.1.0-rc1-cu128", "cu128")
+	if err != nil || version != "2.1.0-rc1" {
+		t.Errorf("BaseVersion = %q, %v", version, err)
+	}
+	if _, err := BaseVersion("2.1.0-cu126", "cu128"); err == nil {
+		t.Error("BaseVersion with mismatched label: want error")
+	}
+	if _, err := BaseVersion("-cu128", "cu128"); err == nil {
+		t.Error("BaseVersion with empty version: want error")
+	}
+}
+
+func TestMatchVariantTag(t *testing.T) {
+	cases := []struct {
+		tag, version string
+		wantLabel    string
+		wantOK       bool
+	}{
+		{"2.1.0-cu128", "2.1.0", "cu128", true},
+		{"2.1.0-null", "2.1.0", "null", true},
+		{"2.1.0-variants", "2.1.0", "", false}, // index tag is not a variant
+		{"2.1.0", "2.1.0", "", false},
+		{"2.1.1-cu128", "2.1.0", "", false},
+		{"2.1.0-CU128", "2.1.0", "", false},
+		{"2.1.0-rc1-cu128", "2.1.0", "", false}, // "rc1-cu128" has an invalid char
+	}
+	for _, c := range cases {
+		label, ok := MatchVariantTag(c.tag, c.version)
+		if ok != c.wantOK || label != c.wantLabel {
+			t.Errorf("MatchVariantTag(%q, %q) = (%q, %v), want (%q, %v)",
+				c.tag, c.version, label, ok, c.wantLabel, c.wantOK)
+		}
+	}
+}
diff --git a/pkg/variant/ordering.go b/pkg/variant/ordering.go
new file mode 100644
index 0000000..f8a63bf
--- /dev/null
+++ b/pkg/variant/ordering.go
@@ -0,0 +1,170 @@
+package variant
+
+import (
+	"cmp"
+	"slices"
+	"strings"
+)
+
+// This file implements the selection algorithm of docs/DESIGN.md §4, ported
+// from PEP 817's variant ordering: filter variants by compatibility with the
+// system properties, then order them by per-property sort keys derived from
+// the index's default-priorities (falling back to the system's own value
+// preference order, then lexicographic order).
+
+// Compatible reports whether a variant's properties are all satisfied by the
+// system properties: every declared (namespace, feature) must have at least
+// one value supported by the system.
+func Compatible(v, sys Properties) bool {
+	for ns, features := range v {
+		for feature, values := range features {
+			supported := sys.Get(ns, feature)
+			if !intersects(values, supported) {
+				return false
+			}
+		}
+	}
+	return true
+}
+
+func intersects(a, b []string) bool {
+	for _, v := range a {
+		if slices.Contains(b, v) {
+			return true
+		}
+	}
+	return false
+}
+
+// rankKey orders one component (namespace, feature, or value). Lower tiers
+// always outrank higher ones:
+//
+//	tier 0: listed in the index default-priorities (pos = list position)
+//	tier 1: ordered by the system's own preference list (values only)
+//	tier 2: lexicographic fallback (name)
+type rankKey struct {
+	tier int
+	pos  int
+	name string
+}
+
+func compareRank(a, b rankKey) int {
+	if c := cmp.Compare(a.tier, b.tier); c != 0 {
+		return c
+	}
+	if c := cmp.Compare(a.pos, b.pos); c != 0 {
+		return c
+	}
+	return strings.Compare(a.name, b.name)
+}
+
+func listRank(list []string, name string) rankKey {
+	if i := slices.Index(list, name); i >= 0 {
+		return rankKey{tier: 0, pos: i}
+	}
+	return rankKey{tier: 2, name: name}
+}
+
+// propertyKey is the (namespace, feature, value) sort key of one matched
+// property.
+type propertyKey struct {
+	ns, feature, value rankKey
+}
+
+func comparePropertyKey(a, b propertyKey) int {
+	if c := compareRank(a.ns, b.ns); c != 0 {
+		return c
+	}
+	if c := compareRank(a.feature, b.feature); c != 0 {
+		return c
+	}
+	return compareRank(a.value, b.value)
+}
+
+// valueRank picks the best rank among the variant's values that the system
+// supports. Index priorities (tier 0) always beat the system's preference
+// order (tier 1).
+func valueRank(prio Priorities, sys Properties, ns, feature string, values []string) rankKey {
+	prioList := prio.Property[ns][feature]
+	supported := sys.Get(ns, feature)
+	best := rankKey{tier: 3}
+	for _, v := range values {
+		var k rankKey
+		switch {
+		case slices.Contains(prioList, v):
+			k = rankKey{tier: 0, pos: slices.Index(prioList, v)}
+		case slices.Contains(supported, v):
+			k = rankKey{tier: 1, pos: slices.Index(supported, v)}
+		default:
+			continue // value not supported by the system: cannot justify rank
+		}
+		if compareRank(k, best) < 0 {
+			best = k
+		}
+	}
+	if best.tier == 3 {
+		// Only reachable on an incompatible variant; callers filter first.
+		best = rankKey{tier: 2, name: strings.Join(values, ",")}
+	}
+	return best
+}
+
+// sortKeys computes the ascending-sorted property keys of a variant.
+func sortKeys(prio Priorities, sys, props Properties) []propertyKey {
+	var keys []propertyKey
+	for ns, features := range props {
+		for feature, values := range features {
+			keys = append(keys, propertyKey{
+				ns:      listRank(prio.Namespace, ns),
+				feature: listRank(prio.Feature[ns], feature),
+				value:   valueRank(prio, sys, ns, feature, values),
+			})
+		}
+	}
+	slices.SortFunc(keys, comparePropertyKey)
+	return keys
+}
+
+// Ranked is one compatible variant with its computed ordering position.
+type Ranked struct {
+	Label string
+	Entry Entry
+}
+
+// Rank returns the index's variants that are compatible with the system
+// properties, best match first. The null variant (zero properties) sorts
+// after every property-bearing compatible variant; callers fall back to the
+// plain base tag only when Rank returns nothing.
+func Rank(ix *Index, sys Properties) []Ranked {
+	type candidate struct {
+		Ranked
+		keys []propertyKey
+	}
+	var candidates []candidate
+	for label, e := range ix.Variants {
+		if !Compatible(e.Properties, sys) {
+			continue
+		}
+		candidates = append(candidates, candidate{
+			Ranked: Ranked{Label: label, Entry: e},
+			keys:   sortKeys(ix.DefaultPriorities, sys, e.Properties),
+		})
+	}
+	slices.SortFunc(candidates, func(a, b candidate) int {
+		for i := range min(len(a.keys), len(b.keys)) {
+			if c := comparePropertyKey(a.keys[i], b.keys[i]); c != 0 {
+				return c
+			}
+		}
+		// Equal prefix: the variant matching more properties wins.
+		if c := cmp.Compare(len(b.keys), len(a.keys)); c != 0 {
+			return c
+		}
+		return strings.Compare(a.Label, b.Label)
+	})
+	out := make([]Ranked, len(candidates))
+	for i, c := range candidates {
+		out[i] = c.Ranked
+	}
+	return out
+}
diff --git a/pkg/variant/ordering_test.go b/pkg/variant/ordering_test.go
new file mode 100644
index 0000000..e97b45a
--- /dev/null
+++ b/pkg/variant/ordering_test.go
@@ -0,0 +1,170 @@
+package variant
+
+import (
+	"slices"
+	"testing"
+)
+
+// sys builds system properties for the common test scenario: an x86-64 v3
+// machine with CUDA 12.8 (which satisfies lower bounds 12.8 down to 12.0).
+func cudaSys() Properties {
+	return Properties{
+		"nvidia": {"cuda_version_lower_bound": {"12.8", "12.6", "12.4", "12.2", "12.0"}},
+		"x86_64": {"level": {"v3", "v2", "v1"}},
+	}
+}
+
+func mustUpsert(t *testing.T, ix *Index, label string, props Properties) {
+	t.Helper()
+	if err := ix.Upsert(label, Entry{Properties: props, Tag: VariantTag(ix.Version, label), Digest: "sha256:" + label}); err != nil {
+		t.Fatalf("Upsert(%q): %v", label, err)
+	}
+}
+
+func rankLabels(ix *Index, sys Properties) []string {
+	var labels []string
+	for _, r := range Rank(ix, sys) {
+		labels = append(labels, r.Label)
+	}
+	return labels
+}
+
+func TestCompatible(t *testing.T) {
+	sys := cudaSys()
+	cases := []struct {
+		name  string
+		props Properties
+		want  bool
+	}{
+		{"empty (null variant)", Properties{}, true},
+		{"satisfied bound", Properties{"nvidia": {"cuda_version_lower_bound": {"12.6"}}}, true},
+		{"unsatisfied bound", Properties{"nvidia": {"cuda_version_lower_bound": {"13.0"}}}, false},
+		{"unknown namespace", Properties{"rocm": {"version": {"6.0"}}}, false},
+		{"multi-value, one matches", Properties{"nvidia": {"cuda_version_lower_bound": {"13.0", "12.0"}}}, true},
+		{"two properties, both must hold", Properties{
+			"nvidia": {"cuda_version_lower_bound": {"12.8"}},
+			"x86_64": {"level": {"v4"}},
+		}, false},
+	}
+	for _, c := range cases {
+		if got := Compatible(c.props, sys); got != c.want {
+			t.Errorf("%s: Compatible = %v, want %v", c.name, got, c.want)
+		}
+	}
+}
+
+func TestRankPrefersHigherCUDA(t *testing.T) {
+	ix := NewIndex("r", "2.1.0")
+	mustUpsert(t, ix, "cu128", Properties{"nvidia": {"cuda_version_lower_bound": {"12.8"}}})
+	mustUpsert(t, ix, "cu120", Properties{"nvidia": {"cuda_version_lower_bound": {"12.0"}}})
+	mustUpsert(t, ix, NullLabel, Properties{})
+
+	// No index priorities: the system's own preference order (12.8 first)
+	// decides, and the null variant sorts last.
+	got := rankLabels(ix, cudaSys())
+	want := []string{"cu128", "cu120", "null"}
+	if !slices.Equal(got, want) {
+		t.Errorf("Rank = %v, want %v", got, want)
+	}
+
+	// An older machine (CUDA 12.4) filters out cu128 entirely.
+	older := Properties{"nvidia": {"cuda_version_lower_bound": {"12.4", "12.2", "12.0"}}}
+	got = rankLabels(ix, older)
+	want = []string{"cu120", "null"}
+	if !slices.Equal(got, want) {
+		t.Errorf("Rank(older) = %v, want %v", got, want)
+	}
+
+	// No GPU at all: only the null variant remains.
+	got = rankLabels(ix, Properties{"x86_64": {"level": {"v3", "v2", "v1"}}})
+	want = []string{"null"}
+	if !slices.Equal(got, want) {
+		t.Errorf("Rank(no GPU) = %v, want %v", got, want)
+	}
+
+	// Nothing compatible and no null variant: empty result (caller falls
+	// back to the plain base tag).
+	delete(ix.Variants, NullLabel)
+	if got := rankLabels(ix, Properties{}); len(got) != 0 {
+		t.Errorf("Rank(incompatible, no null) = %v, want empty", got)
+	}
+}
+
+func TestRankIndexPrioritiesBeatSystemPreference(t *testing.T) {
+	ix := NewIndex("r", "2.1.0")
+	mustUpsert(t, ix, "cu128", Properties{"nvidia": {"cuda_version_lower_bound": {"12.8"}}})
+	mustUpsert(t, ix, "cu120", Properties{"nvidia": {"cuda_version_lower_bound": {"12.0"}}})
+	// The publisher declares 12.0 the preferred build even on newer systems.
+	ix.DefaultPriorities = Priorities{
+		Property: map[string]map[string][]string{
+			"nvidia": {"cuda_version_lower_bound": {"12.0", "12.8"}},
+		},
+	}
+	got := rankLabels(ix, cudaSys())
+	want := []string{"cu120", "cu128"}
+	if !slices.Equal(got, want) {
+		t.Errorf("Rank = %v, want %v", got, want)
+	}
+}
+
+func TestRankNamespacePriority(t *testing.T) {
+	ix := NewIndex("r", "2.1.0")
+	mustUpsert(t, ix, "cuda", Properties{"nvidia": {"cuda_version_lower_bound": {"12.0"}}})
+	mustUpsert(t, ix, "avx", Properties{"x86_64": {"level": {"v3"}}})
+
+	ix.DefaultPriorities = Priorities{Namespace: []string{"nvidia", "x86_64"}}
+	if got := rankLabels(ix, cudaSys()); !slices.Equal(got, []string{"cuda", "avx"}) {
+		t.Errorf("Rank(nvidia first) = %v", got)
+	}
+
+	ix.DefaultPriorities = Priorities{Namespace: []string{"x86_64", "nvidia"}}
+	if got := rankLabels(ix, cudaSys()); !slices.Equal(got, []string{"avx", "cuda"}) {
+		t.Errorf("Rank(x86_64 first) = %v", got)
+	}
+
+	// Unlisted namespaces fall back to lexicographic order: nvidia < x86_64.
+	ix.DefaultPriorities = Priorities{}
+	if got := rankLabels(ix, cudaSys()); !slices.Equal(got, []string{"cuda", "avx"}) {
+		t.Errorf("Rank(lexicographic fallback) = %v", got)
+	}
+}
+
+func TestRankMorePropertiesWin(t *testing.T) {
+	ix := NewIndex("r", "2.1.0")
+	mustUpsert(t, ix, "cu128", Properties{"nvidia": {"cuda_version_lower_bound": {"12.8"}}})
+	mustUpsert(t, ix, "cu128v3", Properties{
+		"nvidia": {"cuda_version_lower_bound": {"12.8"}},
+		"x86_64": {"level": {"v3"}},
+	})
+	ix.DefaultPriorities = Priorities{Namespace: []string{"nvidia", "x86_64"}}
+	got := rankLabels(ix, cudaSys())
+	want := []string{"cu128v3", "cu128"}
+	if !slices.Equal(got, want) {
+		t.Errorf("Rank = %v, want %v (more matched properties must win)", got, want)
+	}
+}
+
+func TestRankMultiValueUsesBestMatch(t *testing.T) {
+	ix := NewIndex("r", "2.1.0")
+	// One image built for both 12.6 and 12.8: its best matching value (12.8)
+	// determines the rank, so it beats the dedicated 12.6 build.
+	mustUpsert(t, ix, "combo", Properties{"nvidia": {"cuda_version_lower_bound": {"12.6", "12.8"}}})
+	mustUpsert(t, ix, "cu126", Properties{"nvidia": {"cuda_version_lower_bound": {"12.6"}}})
+	got := rankLabels(ix, cudaSys())
+	want := []string{"combo", "cu126"}
+	if !slices.Equal(got, want) {
+		t.Errorf("Rank = %v, want %v", got, want)
+	}
+}
+
+func TestRankDeterministicTieBreak(t *testing.T) {
+	ix := NewIndex("r", "2.1.0")
+	mustUpsert(t, ix, "b", Properties{"nvidia": {"cuda_version_lower_bound": {"12.8"}}})
+	mustUpsert(t, ix, "a", Properties{"nvidia": {"cuda_version_lower_bound": {"12.8"}}})
+	for range 10 {
+		got := rankLabels(ix, cudaSys())
+		if !slices.Equal(got, []string{"a", "b"}) {
+			t.Fatalf("Rank = %v, want stable [a b]", got)
+		}
+	}
+}
diff --git a/pkg/variant/property.go b/pkg/variant/property.go
new file mode 100644
index 0000000..11dcbd7
--- /dev/null
+++ b/pkg/variant/property.go
@@ -0,0 +1,132 @@
+// Package variant implements the core data model of PEP 817-style container
+// image variants: variant labels, variant properties, the per-version variant
+// index, and the selection (ordering) algorithm. It is pure — no registry or
+// Docker Engine I/O — so it can be reused by the CLI plugin, the registry
+// proxy, and any future moby/containerd integration.
+//
+// See docs/DESIGN.md for the frozen v1 contracts.
+package variant
+
+import (
+	"fmt"
+	"regexp"
+	"slices"
+	"sort"
+	"strings"
+)
+
+const (
+	// NullLabel is the reserved label for the null variant (zero properties).
+	NullLabel = "null"
+	// ReservedIndexLabel is reserved because "<version>-variants" addresses
+	// the variant index artifact, not a variant image.
+	ReservedIndexLabel = "variants"
+)
+
+var (
+	labelRe     = regexp.MustCompile(`^[0-9a-z._]{1,16}$`)
+	componentRe = regexp.MustCompile(`^[a-z0-9_]+$`)
+	valueRe     = regexp.MustCompile(`^[a-z0-9_.]+$`)
+)
+
+// ValidateLabel checks a variant label against the PEP 817 rule
+// (^[0-9a-z._]{1,16}$) and the reserved names of this project.
+func ValidateLabel(label string) error {
+	if !labelRe.MatchString(label) {
+		return fmt.Errorf("invalid variant label %q: must match %s", label, labelRe.String())
+	}
+	if label == ReservedIndexLabel {
+		return fmt.Errorf("variant label %q is reserved for the variant index tag", label)
+	}
+	return nil
+}
+
+func validateComponent(kind, s string) error {
+	if !componentRe.MatchString(s) {
+		return fmt.Errorf("invalid property %s %q: must match %s", kind, s, componentRe.String())
+	}
+	return nil
+}
+
+// validateValue is looser than validateComponent: feature values may contain
+// dots (version numbers like "12.8").
+func validateValue(s string) error {
+	if !valueRe.MatchString(s) {
+		return fmt.Errorf("invalid property value %q: must match %s", s, valueRe.String())
+	}
+	return nil
+}
+
+// Properties maps namespace -> feature -> ordered list of values.
+//
+// On a variant, the value list enumerates the values the image was built for
+// (multi-value semantics: any one matching the system makes the property
+// satisfied). On a system (detection result), the list enumerates supported
+// values ordered most-preferred first.
+type Properties map[string]map[string][]string
+
+// Add appends values to the (namespace, feature) property, creating it as
+// needed. Duplicate values are dropped, preserving first-seen order.
+func (p Properties) Add(namespace, feature string, values ...string) {
+	features, ok := p[namespace]
+	if !ok {
+		features = make(map[string][]string)
+		p[namespace] = features
+	}
+	for _, v := range values {
+		if !slices.Contains(features[feature], v) {
+			features[feature] = append(features[feature], v)
+		}
+	}
+}
+
+// Get returns the value list for (namespace, feature), or nil.
+func (p Properties) Get(namespace, feature string) []string {
+	return p[namespace][feature]
+}
+
+// Count returns the number of (namespace, feature) properties.
+func (p Properties) Count() int {
+	n := 0
+	for _, features := range p {
+		n += len(features)
+	}
+	return n
+}
+
+// Validate checks every namespace, feature, and value for syntactic validity
+// and rejects properties with empty value lists.
+func (p Properties) Validate() error {
+	for ns, features := range p {
+		if err := validateComponent("namespace", ns); err != nil {
+			return err
+		}
+		for feature, values := range features {
+			if err := validateComponent("feature", feature); err != nil {
+				return err
+			}
+			if len(values) == 0 {
+				return fmt.Errorf("property %s :: %s has no values", ns, feature)
+			}
+			for _, v := range values {
+				if err := validateValue(v); err != nil {
+					return fmt.Errorf("property %s :: %s: %w", ns, feature, err)
+				}
+			}
+		}
+	}
+	return nil
+}
+
+// Triples renders the properties as sorted "ns :: feature :: v1,v2" strings,
+// for stable human-readable output.
+func (p Properties) Triples() []string {
+	var out []string
+	for ns, features := range p {
+		for feature, values := range features {
+			out = append(out, fmt.Sprintf("%s :: %s :: %s", ns, feature, strings.Join(values, ",")))
+		}
+	}
+	sort.Strings(out)
+	return out
+}