indexbuild

type Clock func() time.Time

type Config struct {
	IndexSetID          string
	RunID               string
	GonimbusVersion     string
	GonimbusCommit      string
	GonimbusVCSModified *bool
	BaseURI             string
	Source              Source
	Match               MatchConfig
	Filter              *match.CompositeFilter
	Crawl               crawler.Config
	// MaxJournalLanes bounds how many journal-writing lanes a build may split its
	// crawl across. Experimental.
	//
	// A build funnels every observation through one journal writer, which becomes
	// the ceiling once listing is no longer the constraint. Lanes give each a
	// private crawl pipeline and journal, while one shared request budget keeps
	// listing concurrency and request rate at their configured run-global values.
	//
	// Zero selects the resolved default; one keeps the single-journal form. Values
	// above the engine ceiling are refused before any side effect rather than
	// clamped. The effective lane count is the smallest of this value, the crawl
	// concurrency, and the number of crawl-plan entries — so lanes require an
	// explicit CrawlPrefixes plan with more than one entry, since a plan entry is
	// the unit of coverage authority a lane attests.
	//
	// A multi-lane run seals several journals, each recording only the plan subset
	// it observed. Recovery from such a run must be handed the complete set: an
	// omitted journal narrows the derived plan and refuses whole-run coverage.
	MaxJournalLanes int
	// CrawlPrefixes, when supplied, is the exact provider-prefix observation
	// plan. It lets CLI adapters pass a manifest scope plan into the engine
	// without making the engine import manifest or command packages. Entries
	// must be canonical provider-key prefixes (no leading slash or surrounding
	// whitespace) so the plan compared against coverage is exactly what drives
	// LIST. Coverage must equal this plan exactly (per-prefix set equality, no
	// roll-up/extra/missing/duplicate/windowed and confirmed-complete only) or
	// Build refuses before any side effect. When empty the effective plan is the
	// full base prefix; either way the plan is sealed into the journal as
	// recovery provenance and prior rows outside the attested plan are retained.
	// Any durable build additionally rejects a reducing observation selector
	// (see Match) so the sealed plan is a truthful record of what was observed.
	CrawlPrefixes []string
	// ObservationSinks receive the same observed crawl stream as the durable
	// journal materializer. This is the library-owned fanout boundary used by
	// CLI adapters to materialize compatibility formats from one observation.
	ObservationSinks []output.Writer
	Paths            PathConfig
	Coverage         []CoverageAttestation
	// PriorRows is retained only for source compatibility and is NOT an accepted
	// input: public Build rejects any non-nil value (including an empty non-nil
	// slice) before side effects. Durable prior state is loaded from the verified
	// parent under the held lease at continuity activation, never from
	// caller-supplied rows.
	PriorRows []ObjectState
	// ExpectedParent, when set, enforces latest-pointer CAS at publish advance.
	// When nil, Build/Retry capture the current latest (or first-publish) under
	// the write lease. Malformed latest fails closed (not first-publish).
	// Stale provided tokens are validated immediately after lease acquisition
	// and before any crawl/observation mutation.
	ExpectedParent *ParentToken
	// LossAcknowledgment records an explicit pinned scope-loss acknowledgment
	// bound to the parent manifest SHA-256 and current plan digest. When present,
	// it is sealed into the run's journal headers so recovery re-publications
	// verify the exact recorded acknowledgment rather than ambient flags.
	LossAcknowledgment *durableindex.TransitionAcknowledgment
	// Authority optionally supplies caller-held whole-set exclusion. When nil,
	// Build acquires the same stable authority used by CLI and GC. A supplied
	// lease remains caller-owned and is never released by Build.
	Authority *indexcoord.Lease

	RunStartedAt         time.Time
	ManifestCreatedAt    time.Time
	Clock                Clock
	TargetRowsPerSegment int
	// Spill is host/operator capacity configuration for the durable streaming
	// merge's scratch workspace. Zero values select the substrate defaults.
	Spill  SpillConfig
	Events EventSink
	// OnSegmentProgress is optional observational progress during segment write
	// (counts only). Outside artifact bytes; never a publish failure vector.
	OnSegmentProgress OnSegmentProgressFunc
}

type CoverageAttestation struct {
	Scope    *Scope        `json:"scope,omitempty"`
	Basis    CoverageBasis `json:"basis"`
	Complete bool          `json:"complete"`
	Gaps     []Scope       `json:"gaps,omitempty"`
}

type CoverageBasis string

type Digest struct {
	Algorithm string
	Hex       string
}

type Event struct {
	Type    string         `json:"type"`
	RunID   string         `json:"run_id"`
	Message string         `json:"message,omitempty"`
	Details map[string]any `json:"details,omitempty"`
}

type EventSink interface {
	OnEvent(ctx context.Context, event Event) error
}

type ManifestSummary struct {
	GonimbusVersion        string
	GonimbusCommit         string
	GonimbusVCSModified    *bool
	DotSegmentPolicy       string
	Rows                   int
	ActiveRows             int
	Tombstones             int
	DistinctETags          int
	RetainedUnobservedRows int
	DotSegmentRows         int
	PlanDigest             string
	Admission              string
	Segments               []SegmentSummary
}

type MatchConfig struct {
	Includes      []string
	Excludes      []string
	IncludeHidden bool
}

type ObjectState struct {
	IndexSetID       string
	RelKey           string
	SizeBytes        int64
	LastModified     *time.Time
	ETag             string
	StorageClass     *string
	ArchiveStatus    *string
	RestoreState     *string
	RestoreExpiry    *time.Time
	ContentType      *string
	HeadEnrichedAt   *time.Time
	FirstSeenRunID   string
	FirstSeenAt      time.Time
	LastChangedRunID string
	LastChangedAt    time.Time
	LastSeenRunID    string
	LastSeenAt       time.Time
	DeletedAt        *time.Time
}

type OnSegmentProgressFunc func(progress SegmentProgress)

type ParentToken struct {
	IndexSetID     string
	RunID          string
	ManifestSHA256 string
	// CoverageSHA256 binds inherited coverage for enrich-only publications.
	CoverageSHA256 string
}

type PathConfig struct {
	JournalDir   string
	SegmentDir   string
	ManifestPath string
	CompletePath string
	LatestPath   string
	IndexDBDir   string
}

type RetryConfig struct {
	IndexSetID          string
	RunID               string
	GonimbusVersion     string
	GonimbusCommit      string
	GonimbusVCSModified *bool
	BaseURI             string
	Paths               PathConfig
	JournalPaths        []string
	// Coverage is destructive authority over verified-parent rows: a
	// confirmed-complete scope tombstones unobserved parent keys under it. Public
	// Retry does not trust this field on its own — it derives the observation
	// plan from the recorded `crawl_prefixes` journal header and requires Coverage
	// to match that plan exactly. The footer `content_sha256` is an unkeyed
	// integrity checksum over header+records (verified at validation and at the
	// compaction reopen) that detects corruption, truncation, and partial
	// modification on read; Retry consumes JournalPaths as engine-produced
	// recovery artifacts in trusted working storage. It is not a cryptographic
	// authentication mechanism; stronger authentication for untrusted
	// recovery-artifact storage is a tracked follow-up. Journals without a
	// recorded plan or checksum, or whose recorded plan is non-canonical, fail
	// closed.
	Coverage []CoverageAttestation
	// PriorRows is retained only for source compatibility and is NOT an accepted
	// input: public Retry rejects any non-nil value (including an empty non-nil
	// slice) before side effects. Durable prior state is loaded from the verified
	// parent under the held lease at continuity activation, never from
	// caller-supplied rows.
	PriorRows []ObjectState
	// ExpectedParent enforces latest CAS when republishing over an existing set.
	ExpectedParent *ParentToken
	// LossAcknowledgment, when supplied on Retry, must match the acknowledgment
	// already sealed in the journal headers; Retry never accepts an unsealed
	// acknowledgment override.
	LossAcknowledgment *durableindex.TransitionAcknowledgment
	// Authority follows Config.Authority semantics for public Retry.
	Authority *indexcoord.Lease

	RunStartedAt         time.Time
	ManifestCreatedAt    time.Time
	Clock                Clock
	TargetRowsPerSegment int
	// Spill follows Config.Spill semantics for public Retry.
	Spill             SpillConfig
	Events            EventSink
	OnSegmentProgress OnSegmentProgressFunc
}

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

type Scope struct {
	Prefix string  `json:"prefix,omitempty"`
	Window *Window `json:"window,omitempty"`
}

type SegmentProgress struct {
	Segment  int
	Total    int
	Rows     int
	RowsDone int
}

type SegmentSummary struct {
	SegmentID  string
	Path       string
	Rows       int
	Tombstones int
	Digest     Digest
}

type Source struct {
	Provider     provider.Provider
	ProviderName string
}

type SpillConfig struct {
	// WorkspaceBytes overrides the merge's live on-disk workspace ceiling
	// (MaxWorkspaceBytes). A successive build stages the full prior current-state
	// into this workspace before merging, so size it to the corpus. Zero uses the
	// substrate default; a negative or sub-1 explicit value is rejected at publish.
	WorkspaceBytes int64
	// Root overrides the scratch directory (resolved absolute, real, non-symlink,
	// operator-exclusive at publish). Empty co-locates beside the run journals.
	Root string
	// RecordBytes overrides the max single journal-record (line) size
	// (MaxRecordBytes). The journal header carries the crawl-prefix plan, which
	// grows with scope prefix count, so very wide/dense scopes need a larger
	// bound. Zero uses the substrate default; a sub-1 explicit value is rejected.
	RecordBytes int64
}

type Summary struct {
	IndexSetID      string
	RunID           string
	JournalPaths    []string
	ObjectsObserved int64
	PrefixesCrawled []string
	// ManifestSHA256 is the digest written into the durable complete marker at
	// publish time. Prefer this over re-hashing the manifest path after commit.
	ManifestSHA256 string
	// SnapshotCompletedAt is sampled at the immutable local complete-marker
	// commit boundary and is independent of the run start.
	SnapshotCompletedAt time.Time
	Manifest            ManifestSummary
	// PeakWorkspaceBytes is the high-water live on-disk spill workspace observed
	// during the durable merge (0 when nothing spilled or on the SQLite path).
	// Observational capacity evidence for sizing successive builds.
	PeakWorkspaceBytes int64
}

type Window struct {
	From string `json:"from,omitempty"`
	To   string `json:"to,omitempty"`
}