sqlite

package
v0.1.0 Latest Latest
Warning

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

 Go to latest Published: Nov 3, 2026 License: Apache-2.0 Imports: 41 Imported by: 0

Documentation

Overview

Package sqlite owns the local operational SQLite schema.

Package sqlite implements the durable operational repositories for the Go Core.

Index

Constants

View Source 
const (
	MaxReportProjectionDocumentBytes = 32 << 20
	MaxReportProjectionItemBytes     = 8 << 20
)
View Source 
const (
	CurrentSchemaVersion = 4
)

Variables

View Source 
var (
	ErrNotFound = errors.New("sqlite repository record not found")
	ErrConflict = errors.New("sqlite repository revision conflict")
	ErrCorrupt  = errors.New("sqlite repository data is corrupt")
)
View Source 
var ErrHistoricalJob = errors.New("historical job is read-only after upgrade; create a new job to execute again")

ErrHistoricalJob identifies preserved, read-only jobs which cannot safely be resumed because their original producer did not record executor provenance.

View Source 
var ErrMigrationDataIncompatible = errors.New("historical sqlite data is incompatible with migration")

ErrMigrationDataIncompatible identifies historical content that a migration cannot safely transform. It does not authorize overwriting the source.

View Source 
var ErrSchemaResetRequired = errors.New("unsupported sqlite schema; preserve this database and explicitly upgrade it before opening")

ErrSchemaResetRequired classifies unsupported or invalid persisted formats. The name is retained for callers; this error never authorizes a data reset.

Functions

func CurrentSchemaIdentity 

func CurrentSchemaIdentity() (version int, name, checksum string)

CurrentSchemaIdentity returns the single operational schema marker.

func ExportUpgradeHistory 

func ExportUpgradeHistory(ctx context.Context, path, destination string) (result error)

ExportUpgradeHistory writes a lossless JSONL archive from a consistent, read-only snapshot. It never migrates the source or overwrites an existing destination. A complete export always ends with a complete record.

func FinalizeRecoveryDirectory 

func FinalizeRecoveryDirectory(ctx context.Context, directory string) (string, error)

FinalizeRecoveryDirectory makes completed recovery files durable before the desktop selector can reference them, including Windows directory publication.

func Migrate 

func Migrate(ctx context.Context, path string, options MigrateOptions) error

Migrate upgrades supported operational baselines before normal workspace use. All changes commit together; the pre-upgrade SQLite backup is retained.

func SchemaVersion 

func SchemaVersion(ctx context.Context, path string) (int, error)

SchemaVersion returns the validated operational schema version without mutating the database. A missing path is version zero.

Types

type MigrateOptions 

type MigrateOptions struct {
	AppVersion  string
	BusyTimeout time.Duration
	// Progress reports the current stage without exposing paths or user data.
	Progress func(MigrationProgress)
}

MigrateOptions identifies the application creating the operational schema and controls how long SQLite waits for a competing writer.

type MigrationProgress 

type MigrationProgress struct {
	Stage       string
	FromVersion int
	ToVersion   int
}

type RecoveryBackup 

type RecoveryBackup struct {
	SHA256 string `json:"sha256"`
	Bytes  int64  `json:"bytes"`
}

func BackupIncompatibleDatabase 

func BackupIncompatibleDatabase(ctx context.Context, path, destination string) (RecoveryBackup, error)

BackupIncompatibleDatabase preserves a consistent SQLite snapshot without interpreting its application schema. The source and its sidecars stay in place.

type Repository 

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

Each Repository uses a one-connection pool. Desktop and runner history use a separate read-only view, leaving execution's connection for critical work.

func OpenRepository 

func OpenRepository(ctx context.Context, path string, options RepositoryOptions) (*Repository, error)

func (*Repository) AcceptJob 

func (repository *Repository) AcceptJob(
	ctx context.Context,
	input jobhost.Acceptance,
) (jobcontract.Snapshot, bool, error)

func (*Repository) ActiveJobs 

func (repository *Repository) ActiveJobs(ctx context.Context) ([]jobcontract.Snapshot, error)

func (*Repository) AppendResults 

func (repository *Repository) AppendResults(ctx context.Context, results ...domain.Result) error

AppendResults writes a batch atomically. Callers resolve suite and case identities from the validated run snapshot before writing; appends do not reload run documents.

func (*Repository) ApplyJobCommand 

func (repository *Repository) ApplyJobCommand(
	ctx context.Context,
	command jobcontract.Command,
	at time.Time,
) (jobcontract.CommandConfirmation, bool, error)

func (*Repository) ApplyRemoteBatch 

func (repository *Repository) ApplyRemoteBatch(
	ctx context.Context,
	batch remoteresults.Batch,
) (remoteresults.Mirror, error)

ApplyRemoteBatch imports only already committed facts. It never creates an execution_jobs owner, submits traffic, or infers failure from disconnection.

func (*Repository) AvailableReports 

func (repository *Repository) AvailableReports(ctx context.Context, ids []string) ([]string, error)

AvailableReports checks local archive existence without decoding report bodies.

func (*Repository) ChangeJob 

func (repository *Repository) ChangeJob(ctx context.Context, change jobhost.Change) (jobcontract.Snapshot, error)

func (*Repository) CheckIntegrity 

func (repository *Repository) CheckIntegrity(ctx context.Context) error

CheckIntegrity explicitly audits the whole database. Normal startup and object reads validate their own schema and data without scanning all history.

func (*Repository) CheckWritable 

func (repository *Repository) CheckWritable(ctx context.Context) error

CheckWritable acquires the current writer and validates a write statement without changing any task or journal. Disk headroom is checked separately.

func (*Repository) Close 

func (repository *Repository) Close() error

func (*Repository) ComparisonHistory 

func (repository *Repository) ComparisonHistory(
	ctx context.Context,
	after string,
	refresh []string,
) (comparisons.HistoryPage, error)

ComparisonHistory projects only a bounded window and explicitly refreshed active identities. It never loads report bodies into Go or validates history.

func (*Repository) ContentPublication 

func (repository *Repository) ContentPublication(
	ctx context.Context,
	storeID, sha256 string,
) (jobcontent.Generation, error)

func (*Repository) CreateComparison 

func (repository *Repository) CreateComparison(ctx context.Context, comparison domain.Comparison) error

func (*Repository) CreateControl 

func (repository *Repository) CreateControl(
	ctx context.Context,
	record jobs.ControlRecord,
) (jobs.ControlRecord, error)

func (*Repository) CreateEvidence 

func (repository *Repository) CreateEvidence(ctx context.Context, evidence domain.Evidence) error

func (*Repository) CreateReport 

func (repository *Repository) CreateReport(ctx context.Context, report domain.Report) error

func (*Repository) CreateRun 

func (repository *Repository) CreateRun(ctx context.Context, run domain.Run) error

func (*Repository) CreateSubmission 

func (repository *Repository) CreateSubmission(
	ctx context.Context,
	record jobs.SubmissionRecord,
) (jobs.SubmissionRecord, error)

func (*Repository) GetComparison 

func (repository *Repository) GetComparison(ctx context.Context, id string) (domain.Comparison, error)

func (*Repository) GetControl 

func (repository *Repository) GetControl(ctx context.Context, id string) (jobs.ControlRecord, error)

func (*Repository) GetEvidence 

func (repository *Repository) GetEvidence(ctx context.Context, id string) (domain.Evidence, error)

func (*Repository) GetJob 

func (repository *Repository) GetJob(ctx context.Context, id string) (jobcontract.Snapshot, error)

func (*Repository) GetJobCommand 

func (repository *Repository) GetJobCommand(ctx context.Context, id string) (jobcontract.CommandConfirmation, error)

func (*Repository) GetJobSpec 

func (repository *Repository) GetJobSpec(ctx context.Context, id string) (jobcontract.JobSpec, error)

func (*Repository) GetPerformanceObservation 

func (repository *Repository) GetPerformanceObservation(
	ctx context.Context,
	id string,
) (jobcontract.PerformanceObservation, error)

func (*Repository) GetQuickPerformanceReport 

func (repository *Repository) GetQuickPerformanceReport(ctx context.Context, reportID string) (quicktest.PerformanceReport, error)

func (*Repository) GetRemoteMirror 

func (repository *Repository) GetRemoteMirror(ctx context.Context, id string) (remoteresults.Mirror, error)

func (*Repository) GetReport 

func (repository *Repository) GetReport(ctx context.Context, id string) (domain.Report, error)

func (*Repository) GetResult 

func (repository *Repository) GetResult(ctx context.Context, id string) (domain.Result, error)

func (*Repository) GetRun 

func (repository *Repository) GetRun(ctx context.Context, id string) (domain.Run, error)

func (*Repository) GetRunRevision 

func (repository *Repository) GetRunRevision(ctx context.Context, id string, revision uint64) (domain.Run, error)

func (*Repository) GetSubmission 

func (repository *Repository) GetSubmission(ctx context.Context, id string) (jobs.SubmissionRecord, error)

func (*Repository) ImportRemotePerformanceDocument 

func (repository *Repository) ImportRemotePerformanceDocument(ctx context.Context, input remoteresults.PerformanceDocumentImport) error

func (*Repository) ImportRemoteRunReport 

func (repository *Repository) ImportRemoteRunReport(ctx context.Context, input remoteresults.RunReportImport) error

ImportRemoteRunReport verifies the original downloaded bytes against the committed reference. Report, attachments, seal and download state commit together. File publication and fsync remain the cache owner's responsibility.

func (*Repository) IsLocalComparison 

func (repository *Repository) IsLocalComparison(ctx context.Context, id string) (bool, error)

func (*Repository) Job 

func (repository *Repository) Job(ctx context.Context, id string) (jobs.JobView, error)

func (*Repository) JobContent 

func (repository *Repository) JobContent(ctx context.Context, id string) (jobcontent.Inventory, error)

func (*Repository) JobControls 

func (repository *Repository) JobControls(
	ctx context.Context,
	jobID string,
	after string,
	limit uint32,
) (jobs.ControlPageView, error)

func (*Repository) JobEvents 

func (repository *Repository) JobEvents(
	ctx context.Context,
	id string,
	after uint64,
	limit uint32,
) (jobhost.EventPage, error)

func (*Repository) Jobs 

func (repository *Repository) Jobs(ctx context.Context, after string, limit uint32) (jobs.JobPage, error)

func (*Repository) ListComparisons 

func (repository *Repository) ListComparisons(ctx context.Context) ([]domain.Comparison, error)

func (*Repository) ListEvidence 

func (repository *Repository) ListEvidence(ctx context.Context, runID string) ([]domain.Evidence, error)

func (*Repository) ListJobs 

func (repository *Repository) ListJobs(ctx context.Context, query jobhost.JobListQuery) (jobhost.JobPage, error)

func (*Repository) ListPendingControls 

func (repository *Repository) ListPendingControls(
	ctx context.Context,
	after string,
	limit uint32,
) (jobs.ControlPage, error)

func (*Repository) ListPendingSubmissions 

func (repository *Repository) ListPendingSubmissions(
	ctx context.Context,
	after string,
	limit uint32,
) (jobs.SubmissionPage, error)

func (*Repository) ListQuickHistory 

func (repository *Repository) ListQuickHistory(ctx context.Context, after string) (quickhistory.Projection, error)

ListQuickHistory selects a bounded mixed ID window before projecting results. It never loads report bodies, evidence payloads, or authored catalog files.

func (*Repository) ListQuickPerformanceReportSummaries 

func (repository *Repository) ListQuickPerformanceReportSummaries(ctx context.Context) ([]quicktest.PerformanceArchiveSummary, error)

func (*Repository) ListRecentQuickPerformanceSummaries 

func (repository *Repository) ListRecentQuickPerformanceSummaries(ctx context.Context, limit int) ([]quicktest.PerformanceArchiveSummary, error)

func (*Repository) ListRecentReportProjections 

func (repository *Repository) ListRecentReportProjections(ctx context.Context, limit int) ([]reporting.ReportProjection, error)

func (*Repository) ListRecoveryRuns 

func (repository *Repository) ListRecoveryRuns(ctx context.Context) ([]domain.Run, error)

ListRecoveryRuns reads only unmanaged current non-terminal runs. Job hosts and remote sync recover their own runs; archived documents remain lazy.

func (*Repository) ListRecycledHistory 

func (repository *Repository) ListRecycledHistory(ctx context.Context, after string) (historyrecycle.Page, error)

func (*Repository) ListRemoteDocumentWork 

func (repository *Repository) ListRemoteDocumentWork(
	ctx context.Context,
	query remoteresults.DocumentQuery,
) (remoteresults.DocumentPage, error)

ListRemoteDocumentWork reads only bounded headers and immutable references. One statement keeps sources, references and control anchors in one snapshot. Eligibility is checked after validation, so malformed terminal history cannot disappear through a filter. SQL may scan scoped history; ctx bounds that work.

func (*Repository) ListRemoteDocuments 

func (repository *Repository) ListRemoteDocuments(ctx context.Context, jobID string) ([]remoteresults.DocumentReference, error)

func (*Repository) ListRemoteFactPriorityIDs 

func (repository *Repository) ListRemoteFactPriorityIDs(
	ctx context.Context,
	origin remoteresults.Origin,
	after string,
	limit uint32,
) (remoteresults.PriorityPage, error)

ListRemoteFactPriorityIDs returns active shared-job scheduling hints. Terminal jobs leave this queue even while documents remain unimported. Go validates bounded rows until limit+1 eligible IDs. SQLite may scan and sort the scoped small headers/snapshots first; total work depends on scoped history and respects ctx. Full spec/submission blobs stay out of the sort and Go. Actual synchronization still authenticates full specs and the event journal.

func (*Repository) ListReportProjections 

func (repository *Repository) ListReportProjections(ctx context.Context) ([]reporting.ReportProjection, error)

ListReportProjections reads only the latest report-list scalars. Full document, history and relation validation belongs to GetReport, when the user opens it.

func (*Repository) ListReports 

func (repository *Repository) ListReports(ctx context.Context) ([]domain.Report, error)

func (*Repository) ListReportsForRuns 

func (repository *Repository) ListReportsForRuns(ctx context.Context, runIDs []string) ([]domain.Report, error)

func (*Repository) ListResults 

func (repository *Repository) ListResults(ctx context.Context, runID string) ([]domain.Result, error)

func (*Repository) ListRunHistory 

func (repository *Repository) ListRunHistory(ctx context.Context, after string) ([]workspace.RunProjection, string, error)

ListRunHistory pages standalone runs. Managed children are fetched only for the jobs the user has loaded, through ReadRunSummaries.

func (*Repository) ListRunProjections 

func (repository *Repository) ListRunProjections(ctx context.Context) ([]workspace.RunProjection, error)

ListRunProjections transfers only the list's scalar fields and compact entry progress. Full snapshots, Case definitions and revision history stay behind GetRun/GetRunRevision and the report/result detail read boundaries.

func (*Repository) ListRuns 

func (repository *Repository) ListRuns(ctx context.Context) ([]domain.Run, error)

func (*Repository) LocalExecutorIdentity 

func (repository *Repository) LocalExecutorIdentity(ctx context.Context) (jobhost.LocalIdentity, error)

LocalExecutorIdentity initializes only an unused execution/outbox namespace. Missing or damaged identity beside existing work requires explicit recovery; startup must never mint another owner and abandon its pending jobs.

func (*Repository) LookupJob 

func (repository *Repository) LookupJob(ctx context.Context, input jobhost.Acceptance) (jobcontract.Snapshot, error)

func (*Repository) MarkJobSettled 

func (repository *Repository) MarkJobSettled(ctx context.Context, id string) error

Settlement is a durable boundary after Core report work and reservation release. A crash before this write must retry settlement, never execution.

func (*Repository) OpenDesktopReadOnlyView 

func (repository *Repository) OpenDesktopReadOnlyView(ctx context.Context) (*Repository, error)

OpenDesktopReadOnlyView omits locally recycled history from desktop lists. Protocol and execution reads continue to use the complete stored history.

func (*Repository) OpenReadOnlyView 

func (repository *Repository) OpenReadOnlyView(ctx context.Context) (*Repository, error)

OpenReadOnlyView isolates history reads from execution's connection. Both roles use the same current repository implementation and validation. The owner must stop readers and close this view before closing writer.

func (*Repository) OverviewActivity 

func (repository *Repository) OverviewActivity(ctx context.Context) (overview.Activity, error)

func (*Repository) PerformanceResult 

func (repository *Repository) PerformanceResult(
	ctx context.Context,
	id string,
) (jobs.PerformanceResultView, error)

func (*Repository) PreviewHistoryRecycle 

func (repository *Repository) PreviewHistoryRecycle(
	ctx context.Context,
	target historyrecycle.Target,
) (historyrecycle.Preview, error)

func (*Repository) PublishContent 

func (repository *Repository) PublishContent(
	ctx context.Context,
	publication jobcontent.Publication,
) (jobcontent.Generation, bool, error)

func (*Repository) ReadJob 

func (repository *Repository) ReadJob(ctx context.Context, id string) (jobs.JobRead, error)

func (*Repository) ReadPerformanceArchive 

func (repository *Repository) ReadPerformanceArchive(
	ctx context.Context,
	jobID string,
	reportID string,
) (jobhost.PerformanceArchiveDocument, error)

func (*Repository) ReadPerformanceResult 

func (repository *Repository) ReadPerformanceResult(
	ctx context.Context,
	id string,
) (jobhost.PerformanceResultDocument, error)

func (*Repository) ReadRemotePerformanceResult 

func (repository *Repository) ReadRemotePerformanceResult(ctx context.Context, jobID string) (jobcontract.PerformanceResult, error)

func (*Repository) ReadRunReport 

func (repository *Repository) ReadRunReport(
	ctx context.Context,
	jobID string,
	reportID string,
) (jobhost.RunReportDocument, error)

func (*Repository) ReadRunSummaries 

func (repository *Repository) ReadRunSummaries(ctx context.Context, ids []string) ([]workspace.RunProjection, error)

func (*Repository) ReadUpgradeHistory 

func (repository *Repository) ReadUpgradeHistory(
	ctx context.Context,
	table string,
	after int64,
	limit int,
) (UpgradeHistoryPage, error)

func (*Repository) RecordJobProgress 

func (repository *Repository) RecordJobProgress(
	ctx context.Context,
	id string,
	progress quicktest.PerformanceProgress,
	at time.Time,
) error

func (*Repository) RecordPerformanceObservation 

func (repository *Repository) RecordPerformanceObservation(
	ctx context.Context,
	input jobhost.PerformanceObservationWrite,
) (jobcontract.PerformanceObservation, error)

func (*Repository) RecoveryJobs 

func (repository *Repository) RecoveryJobs(ctx context.Context) ([]jobcontract.Snapshot, error)

Include terminal Jobs whose command or shutdown decision committed before their child Run/Comparison cleanup. Recovery never executes their requests.

func (*Repository) RecycleHistory 

func (repository *Repository) RecycleHistory(
	ctx context.Context,
	target historyrecycle.Target,
	at time.Time,
) (historyrecycle.Entry, error)

func (*Repository) RegisterContentStore 

func (repository *Repository) RegisterContentStore(ctx context.Context, store jobcontent.Store) error

func (*Repository) RemoteNodeRemovalBlocked 

func (repository *Repository) RemoteNodeRemovalBlocked(
	ctx context.Context,
	configurationID string,
	nodeID string,
	installationID string,
) (bool, error)

RemoteNodeRemovalBlocked reads this desktop's durable submissions, mirrors and controls. It does not contact or alter jobs on the remote runner. Empty executor IDs identify an unbound configuration, which must have no jobs.

func (*Repository) RemoteRunReportImported 

func (repository *Repository) RemoteRunReportImported(ctx context.Context, jobID, reportID string) (bool, error)

RemoteRunReportImported distinguishes a pending reference from a verified report without loading its full document or claiming evidence files exist.

func (*Repository) RestoreHistory 

func (repository *Repository) RestoreHistory(ctx context.Context, target historyrecycle.Target) (historyrecycle.Entry, error)

func (*Repository) RunExecutionOrigin 

func (repository *Repository) RunExecutionOrigin(ctx context.Context, runID string) (*domain.ExecutionOrigin, error)

RunExecutionOrigin returns only the executor frozen by durable admission. A current run without a Job owner is explicitly unmanaged and returns nil.

func (*Repository) SaveQuickPerformanceReport 

func (repository *Repository) SaveQuickPerformanceReport(ctx context.Context, report quicktest.PerformanceReport) error

func (*Repository) SealPerformanceResult 

func (repository *Repository) SealPerformanceResult(
	ctx context.Context,
	id string,
	at time.Time,
) (jobhost.PerformanceResultDocument, error)

func (*Repository) UpdateComparison 

func (repository *Repository) UpdateComparison(ctx context.Context, expectedRevision uint64, comparison domain.Comparison) error

func (*Repository) UpdateControl 

func (repository *Repository) UpdateControl(ctx context.Context, next jobs.ControlRecord, expected uint64) error

func (*Repository) UpdateRun 

func (repository *Repository) UpdateRun(ctx context.Context, expectedRevision uint64, run domain.Run) error

func (*Repository) UpdateSubmission 

func (repository *Repository) UpdateSubmission(
	ctx context.Context,
	next jobs.SubmissionRecord,
	expected uint64,
) error

type RepositoryOptions 

type RepositoryOptions struct {
	BusyTimeout time.Duration
}

type RunnerBackup 

type RunnerBackup struct {
	SchemaVersion  int              `json:"schema_version"`
	SchemaName     string           `json:"schema_name"`
	SchemaSHA256   string           `json:"schema_sha256"`
	DatabaseSHA256 string           `json:"database_sha256"`
	DatabaseBytes  int64            `json:"database_bytes"`
	BusinessSHA256 string           `json:"business_sha256"`
	Rows           RunnerBackupRows `json:"rows"`
}

RunnerBackup contains only safe verification facts, suitable for an upgrade journal. DatabaseSHA256 identifies the file bytes; BusinessSHA256 identifies every typed SQLite value in the consistent snapshot, including WAL content.

func BackupRunnerDatabase 

func BackupRunnerDatabase(ctx context.Context, sourcePath, destinationPath string) (RunnerBackup, error)

BackupRunnerDatabase explicitly snapshots a current database. The caller stops admission and the service before invoking it; this helper never does so. It never migrates, checkpoints, or writes the source. An existing destination or SQLite sidecar is a conflict. The caller must own a private destination directory so another process cannot replace files during SQLite's path open.

func VerifyRunnerDatabase 

func VerifyRunnerDatabase(ctx context.Context, path string) (RunnerBackup, error)

VerifyRunnerDatabase validates the single current schema and all stored runner facts through a read-only transaction. No schema is created or upgraded. For an arbitrary WAL database, DatabaseSHA256 is the main file's hash; only BusinessSHA256 includes the transaction's WAL-visible values.

type RunnerBackupRows 

type RunnerBackupRows struct {
	TotalRows          int64 `json:"total_rows"`
	Jobs               int64 `json:"jobs"`
	JobEvents          int64 `json:"job_events"`
	Runs               int64 `json:"runs"`
	RunRevisions       int64 `json:"run_revisions"`
	CaseResults        int64 `json:"case_results"`
	Evidence           int64 `json:"evidence"`
	Reports            int64 `json:"reports"`
	Comparisons        int64 `json:"comparisons"`
	PerformanceReports int64 `json:"performance_reports"`
	Submissions        int64 `json:"submissions"`
}

RunnerBackupRows counts current business records. TotalRows also includes relation tables, the schema marker, and SQLite's AUTOINCREMENT high water marks.

type UpgradeHistoryPage 

type UpgradeHistoryPage struct {
	SourceChecksum string
	Columns        []string
	TotalRows      int64
	After          int64
	Rows           [][]any
}

UpgradeHistoryPage exposes losslessly preserved SQL cells for inspection and export. Blob cells are []byte, integer cells int64, and original JSON remains raw text/blob. These values must never be sent to current job admission.

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.