diagnostic

package
v3.3.2 Latest Latest
Warning

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

Go to latest
Published: Oct 10, 2026 License: MIT Imports: 13 Imported by: 0

Documentation

Index

Constants

View Source
const (
	CheckSessionProjectDirectoryMismatch  = "session_project_directory_mismatch"
	CheckManualSessionNameProjectMismatch = "manual_session_name_project_mismatch"
	CheckSyncMutationRequiredFields       = "sync_mutation_required_fields"
	CheckSyncTargetClosedSpace            = "sync_target_closed_space"
	CheckInvalidSessionIdentity           = "invalid_session_identity"
	CheckOrphanedObservationSession       = "orphaned_observation_session"
	CheckOrphanedPendingRelations         = "orphaned_pending_relations"
	CheckUnownedSessionProject            = "unowned_session_project"
	CheckSQLiteLockContention             = "sqlite_lock_contention"
	CheckAmbiguousActiveRuntimeSessions   = "ambiguous_active_runtime_sessions"
)
View Source
const (
	StatusOK      = "ok"
	StatusWarning = "warning"
	StatusBlocked = "blocked"
	StatusError   = "error"

	SeverityInfo     = "info"
	SeverityWarning  = "warning"
	SeverityError    = "error"
	SeverityBlocking = "blocking"
)
View Source
const ReasonForeignSyncTarget = "foreign_sync_target"

ReasonForeignSyncTarget marks a finding of CheckSyncTargetClosedSpace whose sync_state row carries a target key outside the closed set of legitimate sync targets.

View Source
const ReasonQuarantinedPulledSessionIdentity = "quarantined_pulled_session_identity"

ReasonQuarantinedPulledSessionIdentity marks a finding of CheckInvalidSessionIdentity that describes a pulled session mutation the apply path skipped rather than a corrupt local source row.

Variables

View Source
var ErrInvalidCheck = errors.New("invalid diagnostic check")

Functions

func IsRepairableCode

func IsRepairableCode(code string) bool

IsRepairableCode reports whether a diagnostic check has a repair implementation.

func RegisteredCodes

func RegisteredCodes() []string

func RepairableCodes

func RepairableCodes() []string

RepairableCodes returns the registered repair implementations in stable order for command validation and help output.

Types

type AmbiguousActiveRuntimeSessionsCheck

type AmbiguousActiveRuntimeSessionsCheck struct{}

func (AmbiguousActiveRuntimeSessionsCheck) Code

func (AmbiguousActiveRuntimeSessionsCheck) Run

type CallerBindingAssessment added in v3.2.0

type CallerBindingAssessment struct {
	Status                 string `json:"status"`
	RootState              string `json:"root_state"`
	EffectiveState         string `json:"effective_state"`
	ReasonCode             string `json:"reason_code"`
	SafeNextStep           string `json:"safe_next_step"`
	WriteSuccessGuaranteed bool   `json:"write_success_guaranteed"`
}

CallerBindingAssessment deliberately contains no identifying evidence.

func AssessCallerBinding added in v3.2.0

func AssessCallerBinding(reader CallerSessionReader, in CallerBindingInput) CallerBindingAssessment

AssessCallerBinding reads only the supplied identities. It never selects a continuation, registers sessions, renews leases, or predicts write success.

type CallerBindingInput added in v3.2.0

type CallerBindingInput struct {
	Project            string             `json:"project,omitempty"`
	RuntimeSessionID   string             `json:"runtime_session_id,omitempty"`
	EffectiveSessionID string             `json:"effective_session_id,omitempty"`
	HostContext        *CallerHostContext `json:"host_context,omitempty"`
}

CallerBindingInput is host evidence, never authorization to resume or write.

type CallerHostContext added in v3.2.0

type CallerHostContext struct {
	AppendEntryAvailable *bool `json:"append_entry_available"`
	BranchAvailable      *bool `json:"branch_available"`
}

type CallerSessionReader added in v3.2.0

type CallerSessionReader interface {
	GetSession(string) (*store.Session, error)
}

type CheckResult

type CheckResult struct {
	CheckID              string          `json:"check_id"`
	Result               string          `json:"result"`
	Severity             string          `json:"severity"`
	ReasonCode           string          `json:"reason_code"`
	Message              string          `json:"message"`
	Why                  string          `json:"why"`
	Evidence             json.RawMessage `json:"evidence"`
	SafeNextStep         string          `json:"safe_next_step"`
	RequiresConfirmation bool            `json:"requires_confirmation"`
	Findings             []Finding       `json:"findings,omitempty"`
}

type DetectedProject

type DetectedProject struct {
	Project string `json:"project"`
	Source  string `json:"source"`
	Path    string `json:"path,omitempty"`
}

type DiagnosticCheck

type DiagnosticCheck interface {
	Code() string
	Run(context.Context, Scope) (CheckResult, error)
}

type Finding

type Finding struct {
	CheckID              string          `json:"check_id"`
	Severity             string          `json:"severity"`
	ReasonCode           string          `json:"reason_code"`
	Message              string          `json:"message"`
	Why                  string          `json:"why"`
	Evidence             json.RawMessage `json:"evidence"`
	SafeNextStep         string          `json:"safe_next_step"`
	RequiresConfirmation bool            `json:"requires_confirmation"`
}

type InvalidSessionIdentityCheck

type InvalidSessionIdentityCheck struct{}

func (InvalidSessionIdentityCheck) Code

func (InvalidSessionIdentityCheck) Run

type ManualSessionNameProjectMismatchCheck

type ManualSessionNameProjectMismatchCheck struct{}

func (ManualSessionNameProjectMismatchCheck) Code

func (ManualSessionNameProjectMismatchCheck) Run

type OrphanedObservationSessionCheck

type OrphanedObservationSessionCheck struct{}

func (OrphanedObservationSessionCheck) Code

func (OrphanedObservationSessionCheck) Run

type OrphanedPendingRelationsCheck

type OrphanedPendingRelationsCheck struct{}

func (OrphanedPendingRelationsCheck) Code

func (OrphanedPendingRelationsCheck) Run

Run reports legacy pending relations whose source AND target observations are absent from the active observation set. Such rows can never show a title in `engram conflicts show` and no verdict can ever be recorded against them, so they only inflate the pending backlog. The listing is deliberately unscoped even when scope.Project is set: a relation with both endpoints absent belongs to no project, so a project-scoped query could never return the rows it exists to surface (the same reasoning as UnownedSessionProjectCheck).

type ProjectReclassifyAction

type ProjectReclassifyAction struct {
	SessionID      string `json:"session_id"`
	FromProject    string `json:"from_project"`
	ToProject      string `json:"to_project"`
	ReasonCode     string `json:"reason_code"`
	EvidenceSource string `json:"evidence_source,omitempty"`
	EvidencePath   string `json:"evidence_path,omitempty"`
}

type Registry

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

func DefaultRegistry

func DefaultRegistry() Registry

func NewRegistry

func NewRegistry(checks ...DiagnosticCheck) Registry

func (Registry) Checks

func (r Registry) Checks() []DiagnosticCheck

func (Registry) Lookup

func (r Registry) Lookup(code string) (DiagnosticCheck, error)

type RepairCounts

type RepairCounts struct {
	SessionsPlanned           int64 `json:"sessions_planned"`
	ObservationsPlanned       int64 `json:"observations_planned"`
	PromptsPlanned            int64 `json:"prompts_planned"`
	SessionsApplied           int64 `json:"sessions_applied"`
	ObservationsApplied       int64 `json:"observations_applied"`
	PromptsApplied            int64 `json:"prompts_applied"`
	CorrectedMutationsPlanned int64 `json:"corrected_mutations_planned"`
	CorrectedMutationsApplied int64 `json:"corrected_mutations_applied"`
	RelationsPlanned          int64 `json:"relations_planned"`
	RelationsApplied          int64 `json:"relations_applied"`
}

type RepairMode

type RepairMode string
const (
	RepairModePlan   RepairMode = "plan"
	RepairModeDryRun RepairMode = "dry_run"
	RepairModeApply  RepairMode = "apply"
)

type RepairPlan

type RepairPlan struct {
	Project             string                             `json:"project"`
	Check               string                             `json:"check"`
	Mode                RepairMode                         `json:"mode"`
	Status              string                             `json:"status"`
	Actions             []ProjectReclassifyAction          `json:"actions"`
	TargetActions       []SyncTargetCleanupAction          `json:"target_actions,omitempty"`
	PlaceholderSessions []store.OrphanedSessionPlaceholder `json:"placeholder_sessions,omitempty"`
	IdentityRepair      *store.SessionIdentityRepairPlan   `json:"identity_repair,omitempty"`
	// OrphanedPendingRelations carries the fresh store evidence behind the
	// orphaned_pending_relations repair: candidate rows plus the
	// one-endpoint-missing and live pending counts the repair will not touch.
	OrphanedPendingRelations *store.OrphanedPendingRelationEvidenceReport `json:"orphaned_pending_relations,omitempty"`
	Blockers                 []RepairSkip                                 `json:"blockers,omitempty"`
	Skipped                  []RepairSkip                                 `json:"skipped,omitempty"`
	Counts                   RepairCounts                                 `json:"counts"`
	BackupPath               string                                       `json:"backup_path,omitempty"`
}

func BuildRepairPlan

func BuildRepairPlan(ctx context.Context, scope Scope, report Report, check string, mode RepairMode) (RepairPlan, error)

func PlanSessionIdentityReplacement

func PlanSessionIdentityReplacement(scope Scope, report Report, plan RepairPlan, sourceID string, sourceSelected bool, replacementID string) RepairPlan

PlanSessionIdentityReplacement selects exactly one diagnostic source and delegates collision and journal safety checks to the store's read-only plan. An explicit source selector distinguishes the empty ID from no selection.

type RepairSkip

type RepairSkip struct {
	SessionID  string `json:"session_id,omitempty"`
	ReasonCode string `json:"reason_code"`
	Message    string `json:"message"`
}

type Report

type Report struct {
	Status  string        `json:"status"`
	Project string        `json:"project,omitempty"`
	Summary Summary       `json:"summary"`
	Checks  []CheckResult `json:"checks"`
}

func ErrorReport

func ErrorReport(project string, err error) Report

type Runner

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

func NewRunner

func NewRunner() Runner

func NewRunnerWithRegistry

func NewRunnerWithRegistry(r Registry) Runner

func (Runner) RunAll

func (r Runner) RunAll(ctx context.Context, scope Scope) (Report, error)

func (Runner) RunOne

func (r Runner) RunOne(ctx context.Context, scope Scope, code string) (Report, error)

type SQLiteLockContentionCheck

type SQLiteLockContentionCheck struct{}

func (SQLiteLockContentionCheck) Code

func (SQLiteLockContentionCheck) Run

type Scope

type Scope struct {
	Store                  *store.Store
	Project                string
	Now                    time.Time
	ReadSQLiteLockSnapshot func(context.Context) (store.SQLiteLockSnapshot, error)
	DetectProject          func(string) (DetectedProject, bool)
}

type SessionProjectDirectoryMismatchCheck

type SessionProjectDirectoryMismatchCheck struct{}

func (SessionProjectDirectoryMismatchCheck) Code

func (SessionProjectDirectoryMismatchCheck) Run

type Summary

type Summary struct {
	Total    int `json:"total"`
	OK       int `json:"ok"`
	Warnings int `json:"warnings"`
	Blocked  int `json:"blocked"`
	Errors   int `json:"errors"`
}

type SyncMutationRequiredFieldsCheck

type SyncMutationRequiredFieldsCheck struct{}

func (SyncMutationRequiredFieldsCheck) Code

func (SyncMutationRequiredFieldsCheck) Run

type SyncTargetCleanupAction

type SyncTargetCleanupAction struct {
	TargetKey           string `json:"target_key"`
	RetargetedMutations int64  `json:"retargeted_mutations"`
	RetainedMutations   int64  `json:"retained_mutations"`
	StateRemoved        bool   `json:"state_removed"`
}

SyncTargetCleanupAction identifies one sync target doctor can remove without deleting its journal payloads.

type SyncTargetClosedSpaceCheck

type SyncTargetClosedSpaceCheck struct{}

func (SyncTargetClosedSpaceCheck) Code

func (SyncTargetClosedSpaceCheck) Run

type UnownedSessionProjectCheck

type UnownedSessionProjectCheck struct{}

func (UnownedSessionProjectCheck) Code

func (UnownedSessionProjectCheck) Run

Run reports the sessions that identify no project. A database upgraded from the schema where sessions.project was nullable keeps those rows intact, and they are the population the ownership errors send to doctor, so leaving them unreported would answer that referral with an empty report.

The listing is deliberately unscoped even when scope.Project is set: an unowned session belongs to no project, so a project-scoped query can never return it, and a user who runs `engram doctor --project <name>` after an ownership failure must still be shown the rows that caused it.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL