doctor

package
v0.1.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 5, 2026 License: MIT Imports: 13 Imported by: 0

Documentation

Overview

Package doctor reports redacted, evidence-backed environment readiness.

Index

Constants

View Source 
const LocalSchemaVersion = "mulgae-doctor-result.v1"
View Source 
const (
	// SchemaVersion is the fixed doctor-result contract version.
	SchemaVersion = "mulgae-doctor-result.v1"
)

Variables

This section is empty.

Functions

This section is empty.

Types

type AssignmentState 

type AssignmentState string

AssignmentState reports whether an intended provider can currently join an assignment. Intended providers without authority evidence remain unverified. 

const (
	AssignmentIntendedButUnverified AssignmentState = "intended_but_unverified"
	AssignmentEligible              AssignmentState = "eligible"
	AssignmentIneligible            AssignmentState = "ineligible"
)

type Diagnostic 

type Diagnostic struct {
	Code                     string             `json:"code"`
	Category                 DiagnosticCategory `json:"category"`
	Message                  string             `json:"message"`
	Redacted                 bool               `json:"redacted"`
	CredentialBytesPersisted bool               `json:"credential_bytes_persisted"`
	ArtifactURI              *string            `json:"artifact_uri"`
}

Diagnostic is a redacted user-facing explanation. It intentionally does not carry arbitrary observation errors or environment/configuration bytes.

type DiagnosticCategory 

type DiagnosticCategory string

DiagnosticCategory classifies a redacted doctor diagnostic. 

const (
	DiagnosticConfiguration DiagnosticCategory = "configuration"
	DiagnosticReadiness     DiagnosticCategory = "readiness"
	DiagnosticArtifact      DiagnosticCategory = "artifact"
	DiagnosticSecurity      DiagnosticCategory = "security"
)

type DoctorResult 

type DoctorResult struct {
	SchemaVersion         string             `json:"schema_version"`
	CheckedAt             time.Time          `json:"checked_at"`
	ProjectRoot           string             `json:"project_root"`
	IntendedProviderIDs   []string           `json:"intended_provider_ids"`
	UnverifiedProviderIDs []string           `json:"unverified_provider_ids"`
	ProviderEvidence      []ProviderEvidence `json:"provider_evidence"`
	PlatformEvidence      []PlatformEvidence `json:"platform_evidence"`
	ToolsLock             ToolsLock          `json:"tools_lock"`
	Readiness             Readiness          `json:"readiness"`
	Diagnostics           []Diagnostic       `json:"diagnostics"`
}

DoctorResult is the mulgae-doctor-result.v1 JSON document.

func (DoctorResult) Validate 

func (result DoctorResult) Validate() error

Validate checks the semantic invariants that supplement the JSON contract.

type EvidenceReader 

type EvidenceReader interface {
	ProviderEvidence(context.Context, string) (ProviderEvidenceRecord, error)
	PlatformEvidence(context.Context, PlatformCell) (PlatformEvidenceRecord, error)
	ToolsLock(context.Context) (ToolsLockObservation, error)
}

EvidenceReader is the consumer-owned boundary for recorded authority evidence. It only returns observations; doctor never executes probes, substitutes executables, or reads a hidden evidence/session directory.

type EvidenceState 

type EvidenceState string

EvidenceState is the normalized result of an authority evidence record. 

const (
	EvidenceStatePass         EvidenceState = "pass"
	EvidenceStateInconclusive EvidenceState = "inconclusive"
	EvidenceStateFail         EvidenceState = "fail"
	EvidenceStateUnverified   EvidenceState = "unverified"
)

type EvidenceStatus 

type EvidenceStatus string

EvidenceStatus is the status of one recorded authority predicate. 

const (
	EvidenceStatusPass         EvidenceStatus = "PASS"
	EvidenceStatusFail         EvidenceStatus = "FAIL"
	EvidenceStatusInconclusive EvidenceStatus = "INCONCLUSIVE"
	EvidenceStatusNotRun       EvidenceStatus = "NOT_RUN"
)

type LocalAssignmentProjection 

type LocalAssignmentProjection struct {
	State      string `json:"state"`
	Resilience string `json:"resilience"`
}

type LocalConfigProjection 

type LocalConfigProjection struct {
	Status             string   `json:"status"`
	URI                string   `json:"uri"`
	SHA256             string   `json:"sha256"`
	Authority          string   `json:"authority"`
	Locality           string   `json:"locality"`
	CheckoutHeadOID    string   `json:"checkout_head_oid"`
	IndexEntriesSHA256 string   `json:"index_entries_sha256"`
	TargetCommitOIDs   []string `json:"target_commit_oids"`
	NativeHomeIdentity string   `json:"native_home_identity"`
	ProvenanceState    string   `json:"provenance_state"`
	ReasonCodes        []string `json:"reason_codes"`
}

type LocalDiagnostic 

type LocalDiagnostic struct {
	Code     string `json:"code"`
	Category string `json:"category"`
	Message  string `json:"message"`
	Redacted bool   `json:"redacted"`
}

type LocalDoctorResult 

type LocalDoctorResult struct {
	SchemaVersion         string                      `json:"schema_version"`
	CheckedAt             time.Time                   `json:"checked_at"`
	ProjectRootURI        string                      `json:"project_root_uri"`
	Config                LocalConfigProjection       `json:"config"`
	ConfiguredProviderIDs []string                    `json:"configured_provider_ids"`
	ProviderInventory     []LocalProviderInventoryRow `json:"provider_inventory"`
	Assignment            LocalAssignmentProjection   `json:"assignment"`
	PlatformEvidence      []LocalPlatformEvidence     `json:"platform_evidence"`
	ToolsLock             LocalToolsLock              `json:"tools_lock"`
	Readiness             LocalReadiness              `json:"readiness"`
	Diagnostics           []LocalDiagnostic           `json:"diagnostics"`
}

LocalDoctorResult is the project-local doctor v1 artifact. Field order is part of the machine contract.

func (LocalDoctorResult) Validate 

func (result LocalDoctorResult) Validate() error

type LocalPlatformEvidence 

type LocalPlatformEvidence struct {
	Cell   string `json:"cell"`
	Native bool   `json:"native"`
}

type LocalProviderInventoryRow 

type LocalProviderInventoryRow struct {
	Family string `json:"family"`
	State  string `json:"state"`
	Reason string `json:"reason"`
}

type LocalReadiness 

type LocalReadiness struct {
	State       string   `json:"state"`
	ExitCode    int      `json:"exit_code"`
	ReasonCodes []string `json:"reason_codes"`
}

type LocalToolsLock 

type LocalToolsLock struct {
	State string `json:"state"`
}

type PlatformCell 

type PlatformCell string

PlatformCell is one fixed platform inventory cell. 

const (
	PlatformLinuxAMD64  PlatformCell = "linux-amd64"
	PlatformLinuxARM64  PlatformCell = "linux-arm64"
	PlatformDarwinAMD64 PlatformCell = "darwin-amd64"
	PlatformDarwinARM64 PlatformCell = "darwin-arm64"
)

type PlatformEvidence 

type PlatformEvidence struct {
	Cell           PlatformCell  `json:"cell"`
	Native         bool          `json:"native"`
	EvidenceState  EvidenceState `json:"evidence_state"`
	EvidenceURI    *string       `json:"evidence_uri"`
	EvidenceSHA256 *string       `json:"evidence_sha256"`
	ReasonCodes    []string      `json:"reason_codes"`
}

PlatformEvidence is the redacted readiness projection for one platform cell.

type PlatformEvidenceRecord 

type PlatformEvidenceRecord struct {
	SchemaID string
	Cell     PlatformCell
	URI      string
	SHA256   string
	Native   bool
	Probes   []ProbeObservation
}

PlatformEvidenceRecord is one darwin-arm64 row observed from a platform-contract-evidence.v1 record. Future inventory cells are never read because they cannot become current support evidence.

type ProbeObservation 

type ProbeObservation struct {
	ID     string
	Status EvidenceStatus
}

ProbeObservation is the compact, redaction-safe projection of one required predicate. Its ID must be one of the fixed IDs for the evidence document.

type ProviderEvidence 

type ProviderEvidence struct {
	ProviderID      string          `json:"provider_id"`
	Intended        bool            `json:"intended"`
	AssignmentState AssignmentState `json:"assignment_state"`
	EvidenceState   EvidenceState   `json:"evidence_state"`
	EvidenceURI     *string         `json:"evidence_uri"`
	EvidenceSHA256  *string         `json:"evidence_sha256"`
	ReasonCodes     []string        `json:"reason_codes"`
}

ProviderEvidence is the redacted readiness projection for one provider.

type ProviderEvidenceRecord 

type ProviderEvidenceRecord struct {
	SchemaID                string
	ProviderID              string
	URI                     string
	SHA256                  string
	Probes                  []ProbeObservation
	SecureWriterIndexStatus EvidenceStatus
	AssignmentStatus        EvidenceStatus
}

ProviderEvidenceRecord is a provider-contract-evidence.v1 observation. SHA256 is the unprefixed document digest; doctor emits sha256:<digest>.

type Readiness 

type Readiness struct {
	State       ReadinessState `json:"state"`
	ExitCode    int            `json:"exit_code"`
	ReasonCodes []string       `json:"reason_codes"`
}

Readiness is the terminal doctor readiness result and CLI exit projection.

type ReadinessState 

type ReadinessState string

ReadinessState is the process-readiness projection. 

const (
	ReadinessReady      ReadinessState = "ready"
	ReadinessUnverified ReadinessState = "unverified"
)

type Service 

type Service struct {
	// contains filtered or unexported fields
}

Service observes doctor readiness through injected inward ports. It never imports adapters or performs a provider/platform probe.

func NewService 

func NewService(clock ports.Clock, catalog ports.ContractCatalog, inspector ports.EnvironmentInspector, evidence EvidenceReader, projectRoot ports.AnchoredRoot) (*Service, error)

NewService constructs a doctor service. Evidence is deliberately optional: a nil reader is reported as unverified authority evidence rather than being replaced with a probe or fabricated PASS result.

func (*Service) DiagnoseEnvironment 

func (service *Service) DiagnoseEnvironment(ctx context.Context) (DoctorResult, error)

DiagnoseEnvironment returns a complete redacted doctor result. Operational observations that cannot be obtained remain readiness failures in the result, allowing users to see all independently observed blockers at once.

type Tool 

type Tool struct {
	Name         string `json:"name"`
	ResolvedPath string `json:"resolved_path"`
	Version      string `json:"version"`
	SHA256       string `json:"sha256"`
}

Tool records one locked tool identity.

type ToolObservation 

type ToolObservation struct {
	Name         string
	ResolvedPath string
	Version      string
	SHA256       string
}

ToolObservation records one locked executable without exposing PATH or an environment snapshot.

type ToolsLock 

type ToolsLock struct {
	State  ToolsLockState `json:"state"`
	URI    *string        `json:"uri"`
	SHA256 *string        `json:"sha256"`
	Tools  []Tool         `json:"tools"`
}

ToolsLock records the checked tool-lock observation without environment data.

type ToolsLockObservation 

type ToolsLockObservation struct {
	State  ToolsLockState
	URI    string
	SHA256 string
	Tools  []ToolObservation
}

ToolsLockObservation is the compact observation of the checked tools lock. SHA256 is the unprefixed observed document digest.

type ToolsLockState 

type ToolsLockState string

ToolsLockState is the state of the observed tool-lock record. 

const (
	ToolsLockLocked   ToolsLockState = "locked"
	ToolsLockMissing  ToolsLockState = "missing"
	ToolsLockMismatch ToolsLockState = "mismatch"
)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.