harnessmodelset

Documentation

Overview

Package harnessmodelset declares strict role-indexed model requirements for generated harnesses.

Tier: primitive (1) - see internal/architest. This package may import only packages whose tier is <= 1; an upward import fails the architest gate. See AGENTS.md and internal/architest for the layering contract.

Index

• Constants
• func CanonicalJSON(intent Intent) ([]byte, error)
• type Alternative
• type Diagnostic
  • func Diagnostics(err error) []Diagnostic
• type DiagnosticCode
• type DiagnosticReport
• type EvidenceKind
• type EvidencePolicy
• type Intent
  • func ParseJSON(raw []byte) (Intent, error)
  • func (intent Intent) Validate() error
• type Locality
• type Modality
• type ModelRequirements
• type OperationalConstraints
• type PreferenceMode
• type Privacy
• type Role
• type SelectionPreference
• type ServingProtocol
• type ToolProtocol
• type ValidationError
  • func (e *ValidationError) CanonicalJSON() []byte
  • func (e *ValidationError) Error() string
  • func (e *ValidationError) Report() DiagnosticReport

Constants

const (
	// SchemaV1 is the only model-set intent schema accepted by this package.
	SchemaV1 = "fak-harness-model-set-intent/1"
	// DiagnosticsSchemaV1 identifies the stable validation-report wire format.
	DiagnosticsSchemaV1 = "fak-harness-model-set-diagnostics/1"
)

Functions

func CanonicalJSON

func CanonicalJSON(intent Intent) ([]byte, error)

CanonicalJSON validates intent and emits deterministic, newline-terminated JSON. Roles and set-valued fields are sorted; alternative order is retained.

Types

type Alternative

type Alternative struct {
	ID           string                 `json:"id"`
	Capabilities ModelRequirements      `json:"capabilities,omitempty"`
	Operational  OperationalConstraints `json:"operational,omitempty"`
}

Alternative is one independently satisfiable hard-constraint set. Order in Role.Alternatives is semantic and is therefore preserved by canonical JSON.

type Diagnostic

type Diagnostic struct {
	Code        DiagnosticCode `json:"code"`
	Path        string         `json:"path"`
	Message     string         `json:"message"`
	Remediation string         `json:"remediation"`
}

Diagnostic identifies one invalid field and a deterministic repair.

func Diagnostics

func Diagnostics(err error) []Diagnostic

Diagnostics returns a defensive copy of typed validation diagnostics.

type DiagnosticCode

type DiagnosticCode string

DiagnosticCode is a stable machine-readable refusal class.

const (
	CodeJSONInvalid          DiagnosticCode = "HARNESS_MODEL_SET_JSON_INVALID"
	CodeJSONTrailing         DiagnosticCode = "HARNESS_MODEL_SET_JSON_TRAILING"
	CodeFieldUnknown         DiagnosticCode = "HARNESS_MODEL_SET_FIELD_UNKNOWN"
	CodeFieldDuplicate       DiagnosticCode = "HARNESS_MODEL_SET_FIELD_DUPLICATE"
	CodeFieldRequired        DiagnosticCode = "HARNESS_MODEL_SET_FIELD_REQUIRED"
	CodeValueInvalid         DiagnosticCode = "HARNESS_MODEL_SET_VALUE_INVALID"
	CodeIntentVersionUnknown DiagnosticCode = "HARNESS_MODEL_SET_INTENT_VERSION_UNKNOWN"
	CodeRolesEmpty           DiagnosticCode = "HARNESS_MODEL_SET_ROLES_EMPTY"
	CodeRoleDuplicate        DiagnosticCode = "HARNESS_MODEL_SET_ROLE_DUPLICATE"
	CodeAlternativesEmpty    DiagnosticCode = "HARNESS_MODEL_SET_ALTERNATIVES_EMPTY"
	CodeAlternativeDuplicate DiagnosticCode = "HARNESS_MODEL_SET_ALTERNATIVE_DUPLICATE"
	CodeConstraintsEmpty     DiagnosticCode = "HARNESS_MODEL_SET_CONSTRAINTS_EMPTY"
	CodeConstraintAmbiguous  DiagnosticCode = "HARNESS_MODEL_SET_CONSTRAINT_AMBIGUOUS"
	CodeConstraintConflict   DiagnosticCode = "HARNESS_MODEL_SET_CONSTRAINT_CONFLICT"
	CodeValueDuplicate       DiagnosticCode = "HARNESS_MODEL_SET_VALUE_DUPLICATE"
	CodeFreshnessInvalid     DiagnosticCode = "HARNESS_MODEL_SET_FRESHNESS_INVALID"
)

type DiagnosticReport

type DiagnosticReport struct {
	Schema      string       `json:"schema"`
	Diagnostics []Diagnostic `json:"diagnostics"`
}

DiagnosticReport is the stable JSON envelope for fail-closed diagnostics.

type EvidenceKind

type EvidenceKind string

const (
	EvidenceModelBehaviorProbe  EvidenceKind = "model-behavior-probe"
	EvidenceRuntimeProbe        EvidenceKind = "runtime-probe"
	EvidenceOperatorAttestation EvidenceKind = "operator-attestation"
)

type EvidencePolicy

type EvidencePolicy struct {
	MaxAgeHours   int64          `json:"max_age_hours"`
	RequiredKinds []EvidenceKind `json:"required_kinds,omitempty"`
}

EvidencePolicy bounds the age and accepted kinds of inventory evidence.

type Intent

type Intent struct {
	Schema string `json:"schema"`
	Roles  []Role `json:"roles"`
}

Intent declares the model capabilities a generated harness needs. It names requirements only; inventory observations and candidate selection belong to later model-set leaves.

func ParseJSON

func ParseJSON(raw []byte) (Intent, error)

ParseJSON strictly decodes and validates one v1 intent. Unknown fields, duplicate object keys, missing required wire fields, trailing documents, and invalid hard constraints all return *ValidationError and no partial intent.

func (Intent) Validate

func (intent Intent) Validate() error

Validate enforces the complete v1 contract without consulting an inventory, network, clock, or ambient policy.

type Locality

type Locality string

const (
	LocalityLocalOnly     Locality = "local-only"
	LocalityRemoteAllowed Locality = "remote-allowed"
)

type Modality

type Modality string

const (
	ModalityText  Modality = "text"
	ModalityImage Modality = "image"
	ModalityAudio Modality = "audio"
)

type ModelRequirements

type ModelRequirements struct {
	Family             string       `json:"family,omitempty"`
	Quantization       string       `json:"quantization,omitempty"`
	ToolCalling        *bool        `json:"tool_calling,omitempty"`
	StructuredOutput   *bool        `json:"structured_output,omitempty"`
	ToolProtocol       ToolProtocol `json:"tool_protocol,omitempty"`
	MinimumInputTokens *int64       `json:"minimum_input_tokens,omitempty"`
	Modalities         []Modality   `json:"modalities,omitempty"`
}

ModelRequirements declares witnessed model behavior. Pointer booleans distinguish an omitted constraint from an explicit false, which is rejected as ambiguous for this positive-requirement schema.

type OperationalConstraints

type OperationalConstraints struct {
	Runtime          string          `json:"runtime,omitempty"`
	ServingProtocol  ServingProtocol `json:"serving_protocol,omitempty"`
	Platforms        []string        `json:"platforms,omitempty"`
	Accelerators     []string        `json:"accelerators,omitempty"`
	MaxMemoryBytes   *int64          `json:"max_memory_bytes,omitempty"`
	Locality         Locality        `json:"locality,omitempty"`
	Privacy          Privacy         `json:"privacy,omitempty"`
	LicenseAllowlist []string        `json:"license_allowlist,omitempty"`
}

OperationalConstraints bounds where and how a compatible candidate may run. Runtime is an immutable inventory vocabulary key; the remaining enumerations are schema-owned so unknown values fail closed before resolution.

type PreferenceMode

type PreferenceMode string

const (
	PreferenceDeclaredOrder PreferenceMode = "declared-order"
	PreferenceLocalFirst    PreferenceMode = "local-first"
	PreferenceLowestMemory  PreferenceMode = "lowest-memory"
)

type Privacy

type Privacy string

const (
	PrivacyNoEgress        Privacy = "no-egress"
	PrivacyPrivateEndpoint Privacy = "private-endpoint"
	PrivacyPublicEndpoint  Privacy = "public-endpoint"
)

type Role

type Role struct {
	ID           string               `json:"id"`
	Required     bool                 `json:"required"`
	Alternatives []Alternative        `json:"alternatives"`
	Preference   *SelectionPreference `json:"preference,omitempty"`
	Evidence     EvidencePolicy       `json:"evidence"`
}

Role is one stable harness responsibility and its ordered compatible alternatives. Required must be present on the JSON wire even when false.

type SelectionPreference

type SelectionPreference struct {
	Mode PreferenceMode `json:"mode"`
}

SelectionPreference applies only after every hard constraint is satisfied.

type ServingProtocol

type ServingProtocol string

const (
	ServingProtocolOpenAI    ServingProtocol = "openai-compatible"
	ServingProtocolAnthropic ServingProtocol = "anthropic-compatible"
	ServingProtocolGRPC      ServingProtocol = "grpc"
	ServingProtocolInProcess ServingProtocol = "in-process"
)

type ToolProtocol

type ToolProtocol string

const (
	ToolProtocolOpenAI    ToolProtocol = "openai-tools"
	ToolProtocolAnthropic ToolProtocol = "anthropic-tools"
	ToolProtocolMCP       ToolProtocol = "mcp-tools"
)

type ValidationError

type ValidationError struct {
	Diagnostics []Diagnostic
}

ValidationError carries sorted typed diagnostics. Callers should branch on Diagnostic.Code rather than parsing Error's human-readable rendering.

func (*ValidationError) CanonicalJSON

func (e *ValidationError) CanonicalJSON() []byte

CanonicalJSON renders a byte-stable diagnostic report with a trailing newline.

func (*ValidationError) Error

func (e *ValidationError) Error() string

func (*ValidationError) Report

func (e *ValidationError) Report() DiagnosticReport

Report returns a copy of the stable diagnostic envelope.