sqlite

package
v0.1.5 Latest Latest
Warning

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

Go to latest
Published: Nov 4, 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 PreflightRunnerUpgradeDatabase added in v0.1.5

func PreflightRunnerUpgradeDatabase(ctx context.Context, path string) error

PreflightRunnerUpgradeDatabase checks compatibility before admission or service state changes. Only a private, disposable snapshot enters the shipped Migrate implementation; its recoverable migration backups are disposed of with it.

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 BackupRunnerUpgradeDatabase added in v0.1.5

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

BackupRunnerUpgradeDatabase preserves a supported original schema, including committed WAL data. Historical schemas are rehearsed on a disposable copy; neither their backup nor their source is migrated in place.

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.

func VerifyRunnerUpgradeDatabase added in v0.1.5

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

VerifyRunnerUpgradeDatabase validates backup facts in their original version. It does not initialize, migrate, or reinterpret historical business documents. Current-schema backups retain VerifyRunnerDatabase's full validation contract.

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

Jump to

Keyboard shortcuts

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