Reconcile the canonical model and discovery with the runtime

Closes gap G02 of the scope assessment for the client-registration and discovery
surface. spec/canonical-model.yaml and domain/model.go both claimed to be the
source of truth and disagreed: the spec restricted grants to authorization_code,
required redirect URIs of every client, and omitted the audience, service
subject, tenant, role, MFA and handoff fields the runtime reads.

The durable part is the link, not the edit. A two-way conformance test compares
the spec against the Go model by reflection and fails when a runtime field has
no spec entry or a spec entry is not read by the runtime, the latter unless
marked runtime: false. It found drift beyond the assessment's list on its first
run -- User.tenant was undeclared -- which is the argument for the check over a
one-time reconciliation.

Discovery now advertises the core profile claims that appear on every token and
derives scopes_supported from the registered clients rather than a fixed list.

The Go model is stated as the runtime authority and the YAML as the reviewed
contract, in both files. This covers client registration and discovery, not
schema enforcement in general, which remains G06.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NV9oijZukGyGbRQGGKnK4P

Assistant: claude-code
Assistant-Model: opus
Assistant-Process: 713576@bnt-lap001
Assistant-Session: 384c511d-9bce-4cb8-a676-2aef6c0c8df6

src/internal/domain/conformance_test.go

@@ -0,0 +1,126 @@
+package domain_test
+
+import (
+	"os"
+	"path/filepath"
+	"reflect"
+	"strings"
+	"testing"
+
+	"gopkg.in/yaml.v3"
+
+	"keycape/internal/domain"
+)
+
+// KEY-WP-0017-T02 — the executable link between spec/canonical-model.yaml and
+// the runtime model. Reconciling the two files by hand leaves them free to drift
+// again immediately; this fails the build when they do, in either direction.
+//
+// The contract is deliberately two-way:
+//
+//   - every YAML-serialised field of domain.Client must have a spec entry, so a
+//     new runtime field cannot be added without describing it; and
+//   - every spec field must either exist in the Go model or carry
+//     `runtime: false`, so declaring a field the runtime ignores is a visible,
+//     reviewable act rather than an omission.
+//
+// Fields tagged `yaml:"-"` are excluded by construction: they are runtime policy
+// or secret material, not identity data the canonical model describes.
+
+type specModel struct {
+	Entities map[string]struct {
+		Fields map[string]struct {
+			Runtime *bool `yaml:"runtime"`
+		} `yaml:"fields"`
+	} `yaml:"entities"`
+}
+
+func loadSpec(t *testing.T) specModel {
+	t.Helper()
+	path := filepath.Join("..", "..", "..", "spec", "canonical-model.yaml")
+	raw, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatalf("read canonical model: %v", err)
+	}
+	var model specModel
+	if err := yaml.Unmarshal(raw, &model); err != nil {
+		t.Fatalf("parse canonical model: %v", err)
+	}
+	if len(model.Entities) == 0 {
+		t.Fatal("canonical model declares no entities")
+	}
+	return model
+}
+
+// serialisedFields returns the YAML field names of a struct, skipping those
+// explicitly excluded with `yaml:"-"`.
+func serialisedFields(t *testing.T, v interface{}) map[string]bool {
+	t.Helper()
+	typ := reflect.TypeOf(v)
+	fields := make(map[string]bool, typ.NumField())
+	for i := 0; i < typ.NumField(); i++ {
+		tag := typ.Field(i).Tag.Get("yaml")
+		name := strings.Split(tag, ",")[0]
+		if name == "" || name == "-" {
+			continue
+		}
+		fields[name] = true
+	}
+	return fields
+}
+
+func TestCanonicalModelMatchesRuntimeClient(t *testing.T) {
+	spec := loadSpec(t)
+	entity, ok := spec.Entities["Client"]
+	if !ok {
+		t.Fatal("canonical model has no Client entity")
+	}
+	goFields := serialisedFields(t, domain.Client{})
+
+	for name := range goFields {
+		field, ok := entity.Fields[name]
+		if !ok {
+			t.Errorf("domain.Client field %q has no entry in spec/canonical-model.yaml", name)
+			continue
+		}
+		if field.Runtime != nil && !*field.Runtime {
+			t.Errorf("spec field %q is marked runtime:false but domain.Client reads it", name)
+		}
+	}
+
+	for name, field := range entity.Fields {
+		if goFields[name] {
+			continue
+		}
+		if field.Runtime == nil || *field.Runtime {
+			t.Errorf("spec field Client.%q is not read by domain.Client; add runtime: false if that is deliberate", name)
+		}
+	}
+}
+
+// The same two-way check for the directory entities the migration and validator
+// paths serialise.
+func TestCanonicalModelMatchesRuntimeDirectoryEntities(t *testing.T) {
+	spec := loadSpec(t)
+	for entityName, value := range map[string]interface{}{
+		"User":       domain.User{},
+		"Group":      domain.Group{},
+		"Membership": domain.Membership{},
+	} {
+		entity, ok := spec.Entities[entityName]
+		if !ok {
+			t.Errorf("canonical model has no %s entity", entityName)
+			continue
+		}
+		for name := range serialisedFields(t, value) {
+			field, ok := entity.Fields[name]
+			if !ok {
+				t.Errorf("domain.%s field %q has no entry in spec/canonical-model.yaml", entityName, name)
+				continue
+			}
+			if field.Runtime != nil && !*field.Runtime {
+				t.Errorf("spec field %s.%q is marked runtime:false but the runtime reads it", entityName, name)
+			}
+		}
+	}
+}

src/internal/domain/model.go

@@ -1,6 +1,13 @@
 // Package domain contains the canonical identity model for KeyCape.
-// This is the source of truth for all user, group, client, and MFA data.
-// All provisioning, tests, and migrations derive from these types.
+//
+// These types are the runtime authority for all user, group, client and MFA
+// data: the server reads them, not spec/canonical-model.yaml. That YAML is the
+// reviewed contract, and conformance_test.go holds the two together — adding a
+// serialised field here without describing it there fails the build, and so
+// does describing a field there that nothing here reads (KEY-WP-0017).
+//
+// Fields tagged `yaml:"-"` are outside the canonical model by construction:
+// they are runtime policy or secret material, not identity data.
 package domain
 
 import "time"