Generate contract types, pin fixtures to spec, add build and ADRs

Completes FLUID-WP-0002. The record types in internal/contract are
generated from schemas/ by a dependency-free generator; fixtures
transcribed from the spec's worked examples validate against those
schemas and round-trip through the generated types with
DisallowUnknownFields, so a spec change that misses the schemas fails
CI rather than drifting silently.

Adds identifier prefix helpers, Makefile, GitHub Actions, and five ADRs
recording the Go choice, out-of-process attachment, the wire contract as
boundary, the evidence store, and revision identity.

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

Assistant: claude-code
Assistant-Model: opus
Assistant-Process: 1116572@bnt-lap001
Assistant-Session: 8ba9bb93-a72a-4883-b189-2499cce5c400

internal/contract/telemetry_envelope_gen.go

@@ -0,0 +1,172 @@
+// Code generated by tools/schemagen. DO NOT EDIT.
+// Source: schemas/. Regenerate with `make generate`.
+
+package contract
+
+type FluidTelemetryAdoptionEvent string
+
+const (
+	FluidTelemetryAdoptionEventFirstUse            FluidTelemetryAdoptionEvent = "first_use"
+	FluidTelemetryAdoptionEventContinuedUse        FluidTelemetryAdoptionEvent = "continued_use"
+	FluidTelemetryAdoptionEventMigration           FluidTelemetryAdoptionEvent = "migration"
+	FluidTelemetryAdoptionEventReversion           FluidTelemetryAdoptionEvent = "reversion"
+	FluidTelemetryAdoptionEventDeprecationResponse FluidTelemetryAdoptionEvent = "deprecation_response"
+)
+
+// Valid reports whether v is a defined FluidTelemetryAdoptionEvent.
+func (v FluidTelemetryAdoptionEvent) Valid() bool {
+	switch v {
+	case FluidTelemetryAdoptionEventFirstUse, FluidTelemetryAdoptionEventContinuedUse, FluidTelemetryAdoptionEventMigration, FluidTelemetryAdoptionEventReversion, FluidTelemetryAdoptionEventDeprecationResponse:
+		return true
+	}
+	return false
+}
+
+type FluidTelemetryAdoption struct {
+	Event        FluidTelemetryAdoptionEvent `json:"event" yaml:"event"`
+	FromRevision *RevisionID                 `json:"from_revision,omitempty" yaml:"from_revision,omitempty"`
+}
+
+type FluidTelemetryErrorClass string
+
+const (
+	FluidTelemetryErrorClassValidation           FluidTelemetryErrorClass = "validation"
+	FluidTelemetryErrorClassUnknownPath          FluidTelemetryErrorClass = "unknown_path"
+	FluidTelemetryErrorClassUnknownField         FluidTelemetryErrorClass = "unknown_field"
+	FluidTelemetryErrorClassUnsupportedParameter FluidTelemetryErrorClass = "unsupported_parameter"
+	FluidTelemetryErrorClassAuthorization        FluidTelemetryErrorClass = "authorization"
+	FluidTelemetryErrorClassBackendFailure       FluidTelemetryErrorClass = "backend_failure"
+	FluidTelemetryErrorClassTimeout              FluidTelemetryErrorClass = "timeout"
+	FluidTelemetryErrorClassPolicyRejection      FluidTelemetryErrorClass = "policy_rejection"
+)
+
+// Valid reports whether v is a defined FluidTelemetryErrorClass.
+func (v FluidTelemetryErrorClass) Valid() bool {
+	switch v {
+	case FluidTelemetryErrorClassValidation, FluidTelemetryErrorClassUnknownPath, FluidTelemetryErrorClassUnknownField, FluidTelemetryErrorClassUnsupportedParameter, FluidTelemetryErrorClassAuthorization, FluidTelemetryErrorClassBackendFailure, FluidTelemetryErrorClassTimeout, FluidTelemetryErrorClassPolicyRejection:
+		return true
+	}
+	return false
+}
+
+type FluidTelemetryError struct {
+	Class FluidTelemetryErrorClass `json:"class" yaml:"class"`
+
+	// Redacted. Must not carry backend internals or consumer data.
+	Detail string `json:"detail,omitempty" yaml:"detail,omitempty"`
+	Field  string `json:"field,omitempty" yaml:"field,omitempty"`
+}
+
+// ArchitectureBlueprint.md section 6.1.
+type FluidTelemetryKind string
+
+const (
+	FluidTelemetryKindRequest  FluidTelemetryKind = "request"
+	FluidTelemetryKindError    FluidTelemetryKind = "error"
+	FluidTelemetryKindSequence FluidTelemetryKind = "sequence"
+	FluidTelemetryKindAdoption FluidTelemetryKind = "adoption"
+	FluidTelemetryKindFeedback FluidTelemetryKind = "feedback"
+)
+
+// Valid reports whether v is a defined FluidTelemetryKind.
+func (v FluidTelemetryKind) Valid() bool {
+	switch v {
+	case FluidTelemetryKindRequest, FluidTelemetryKindError, FluidTelemetryKindSequence, FluidTelemetryKindAdoption, FluidTelemetryKindFeedback:
+		return true
+	}
+	return false
+}
+
+// What the privacy filter removed. Recorded so analysis knows what it cannot see.
+type FluidTelemetryRedaction struct {
+	Applied bool     `json:"applied" yaml:"applied"`
+	Rules   []string `json:"rules,omitempty" yaml:"rules,omitempty"`
+}
+
+type FluidTelemetryRequest struct {
+	LatencyMS     *float64 `json:"latency_ms,omitempty" yaml:"latency_ms,omitempty"`
+	Method        string   `json:"method,omitempty" yaml:"method,omitempty"`
+	Operation     string   `json:"operation,omitempty" yaml:"operation,omitempty"`
+	RequestBytes  *int64   `json:"request_bytes,omitempty" yaml:"request_bytes,omitempty"`
+	ResponseBytes *int64   `json:"response_bytes,omitempty" yaml:"response_bytes,omitempty"`
+	Route         string   `json:"route,omitempty" yaml:"route,omitempty"`
+	Status        *int64   `json:"status,omitempty" yaml:"status,omitempty"`
+}
+
+type FluidTelemetryResolutionReason string
+
+const (
+	FluidTelemetryResolutionReasonExplicitRevision     FluidTelemetryResolutionReason = "explicit_revision"
+	FluidTelemetryResolutionReasonBoundContract        FluidTelemetryResolutionReason = "bound_contract"
+	FluidTelemetryResolutionReasonExperimentAssignment FluidTelemetryResolutionReason = "experiment_assignment"
+	FluidTelemetryResolutionReasonCohortRule           FluidTelemetryResolutionReason = "cohort_rule"
+	FluidTelemetryResolutionReasonStableDefault        FluidTelemetryResolutionReason = "stable_default"
+)
+
+// Valid reports whether v is a defined FluidTelemetryResolutionReason.
+func (v FluidTelemetryResolutionReason) Valid() bool {
+	switch v {
+	case FluidTelemetryResolutionReasonExplicitRevision, FluidTelemetryResolutionReasonBoundContract, FluidTelemetryResolutionReasonExperimentAssignment, FluidTelemetryResolutionReasonCohortRule, FluidTelemetryResolutionReasonStableDefault:
+		return true
+	}
+	return false
+}
+
+// Why this revision was chosen. Revision resolution must be deterministic and
+// auditable (ArchitectureBlueprint.md section 5.2).
+type FluidTelemetryResolution struct {
+	PolicyGeneration *int64                         `json:"policy_generation,omitempty" yaml:"policy_generation,omitempty"`
+	Reason           FluidTelemetryResolutionReason `json:"reason" yaml:"reason"`
+}
+
+// Interaction topology is often more informative than error counts
+// (ArchitectureBlueprint.md section 6.4).
+type FluidTelemetrySequence struct {
+	ChainID     string `json:"chain_id,omitempty" yaml:"chain_id,omitempty"`
+	Pattern     string `json:"pattern,omitempty" yaml:"pattern,omitempty"`
+	Position    *int64 `json:"position,omitempty" yaml:"position,omitempty"`
+	RepeatCount *int64 `json:"repeat_count,omitempty" yaml:"repeat_count,omitempty"`
+}
+
+type FluidTelemetry struct {
+	Adoption *FluidTelemetryAdoption `json:"adoption,omitempty" yaml:"adoption,omitempty"`
+	Cohort   *CohortID               `json:"cohort,omitempty" yaml:"cohort,omitempty"`
+
+	// Pseudonymous and stable. Never a raw end-user identifier.
+	ConsumerRef string `json:"consumer_ref,omitempty" yaml:"consumer_ref,omitempty"`
+
+	// Ties an event to the response the consumer saw, and to the other events in its
+	// call chain.
+	CorrelationID string               `json:"correlation_id,omitempty" yaml:"correlation_id,omitempty"`
+	Error         *FluidTelemetryError `json:"error,omitempty" yaml:"error,omitempty"`
+	Experiment    *ExperimentID        `json:"experiment,omitempty" yaml:"experiment,omitempty"`
+	FeedbackRef   *FeedbackID          `json:"feedback_ref,omitempty" yaml:"feedback_ref,omitempty"`
+	ID            string               `json:"id" yaml:"id"`
+	InterfaceID   InterfaceID          `json:"interface_id" yaml:"interface_id"`
+
+	// ArchitectureBlueprint.md section 6.1.
+	Kind       FluidTelemetryKind `json:"kind" yaml:"kind"`
+	OccurredAt Timestamp          `json:"occurred_at" yaml:"occurred_at"`
+
+	// What the privacy filter removed. Recorded so analysis knows what it cannot see.
+	Redaction *FluidTelemetryRedaction `json:"redaction,omitempty" yaml:"redaction,omitempty"`
+	Request   *FluidTelemetryRequest   `json:"request,omitempty" yaml:"request,omitempty"`
+
+	// Why this revision was chosen. Revision resolution must be deterministic and
+	// auditable (ArchitectureBlueprint.md section 5.2).
+	Resolution    *FluidTelemetryResolution `json:"resolution,omitempty" yaml:"resolution,omitempty"`
+	Revision      *RevisionID               `json:"revision,omitempty" yaml:"revision,omitempty"`
+	SchemaVersion SchemaVersion             `json:"schema_version" yaml:"schema_version"`
+
+	// Interaction topology is often more informative than error counts
+	// (ArchitectureBlueprint.md section 6.4).
+	Sequence *FluidTelemetrySequence `json:"sequence,omitempty" yaml:"sequence,omitempty"`
+}
+
+// The normalized interaction event. Designed for interface learning, not
+// unrestricted behavioral capture: raw payload capture is never the default and
+// redaction happens before an event reaches the store (ArchitectureBlueprint.md
+// section 6.2).
+type TelemetryEnvelopeDocument struct {
+	FluidTelemetry FluidTelemetry `json:"fluid_telemetry" yaml:"fluid_telemetry"`
+}