indexsubstrate

type AncestryBudget struct {
	MaxDepth          int
	MaxNodes          int
	MaxMarkerBytes    int64
	MaxManifestBytes  int64
	MaxAggregateBytes int64
}

type AncestryMode string

type AncestryNode struct {
	IndexSetID     string
	RunID          string
	ManifestSHA256 string
	Generation     int
	Baseline       bool
	RunStartedAt   time.Time
	// DeltaBoundary is true when this node is the earliest trustworthy
	// continuous boundary (baseline:true). History without lineage behind it
	// is not a delta boundary even if a prior-state source exists.
	DeltaBoundary bool
}

type AncestryResolveConfig struct {
	// Lookup is required when the root claims a non-baseline continuous parent.
	Lookup PublishedRunLookup
	Budget AncestryBudget
	// RequireContinuous fails closed on legacy (no lineage) instead of
	// returning AncestryModeLegacy.
	RequireContinuous bool
	// ThroughRunID stops the walk after verifying the named root/ancestor.
	// Reaching the lineage baseline first returns baseline_not_ancestor.
	ThroughRunID string
}

type AncestryResult struct {
	Mode AncestryMode
	// Chain is root-first toward the baseline (root, parent, ..., baseline).
	Chain []AncestryNode
	// DeltaBoundary is set when the walk reaches the continuity baseline. An
	// earlier ThroughRunID stop leaves it nil.
	DeltaBoundary *AncestryNode
	// RequestedBoundary is set when ThroughRunID names a verified node. Unlike
	// DeltaBoundary, it may be any continuous ancestor, including the root.
	RequestedBoundary *AncestryNode
	// AccountedBytes is the total marker+manifest bytes charged across the graph.
	AccountedBytes int64
}

type BoundaryManifest struct {
	Type               string                      `json:"type"`
	Render             string                      `json:"render"`
	IndexSetID         string                      `json:"index_set_id"`
	RunID              string                      `json:"run_id"`
	IndexSchemaVersion int                         `json:"index_schema_version"`
	TokenNamespace     string                      `json:"token_namespace"`
	Policies           BoundaryPolicies            `json:"policies"`
	Segments           []BoundarySegmentDescriptor `json:"segments"`
}

type BoundaryPolicies struct {
	TrustModel               string `json:"trust_model"`
	IdentifierPolicy         string `json:"identifier_policy"`
	SegmentShapeMetadata     string `json:"segment_shape_metadata"`
	RestrictedColumnMetadata string `json:"restricted_column_metadata"`
}

type BoundaryRenderConfig struct {
	OutputPath        string
	Source            InternalManifest
	TokenNamespace    string
	RestrictedColumns []string
}

type BoundarySegmentDescriptor struct {
	Token       string        `json:"token"`
	Format      string        `json:"format"`
	Compression string        `json:"compression"`
	Digest      SegmentDigest `json:"digest"`
}

type CompactionInput struct {
	IndexSetID   string
	RunID        string
	RunStartedAt time.Time
	PriorRows    []CurrentObjectRow
	Journals     []Journal
	Coverage     []CoverageAttestation
	// Mode selects tombstone and journal-shape policy. Prefer typed modes over
	// ad-hoc booleans so observe journals cannot accidentally suppress deletes.
	Mode PublicationMode
}

type CompactionResult struct {
	Rows              []CurrentObjectRow
	Tombstones        []Tombstone
	ObservedRecords   int
	EnrichmentRecords int
	// PeakWorkspaceBytes is the high-water live on-disk spill workspace observed
	// during a streaming merge (0 on the non-streaming path or when nothing
	// spilled). Observational capacity evidence, not an artifact field.
	PeakWorkspaceBytes int64
}

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 CurrentObjectRow 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 CurrentStateSource struct {
	// contains filtered or unexported fields
}

type DerivedRefcount struct {
	SegmentID string        `json:"segment_id"`
	Path      string        `json:"path"`
	Digest    SegmentDigest `json:"digest"`
	Count     int           `json:"count"`
}

type ExpectedParentToken struct {
	IndexSetID     string
	RunID          string
	ManifestSHA256 string
	// CoverageSHA256 is the digest of the parent's coverage attestation bytes
	// (canonical JSON). Required for enrich-only; child coverage must match.
	CoverageSHA256 string
}

type InternalManifest struct {
	Type               string    `json:"type"`
	Render             string    `json:"render"`
	IndexSetID         string    `json:"index_set_id"`
	RunID              string    `json:"run_id"`
	IndexSchemaVersion int       `json:"index_schema_version"`
	CreatedAt          time.Time `json:"created_at"`
	// RunStartedAt is the optional authoritative run start.
	// Not an alias of CreatedAt, journal start, or complete-marker time.
	// Omitted on pre-continuity / legacy manifests; never invent from other
	// timestamps. Pointer so JSON omitempty works (time.Time zero is not omitted).
	// When Lineage is present, a non-zero UTC value is required.
	RunStartedAt *time.Time `json:"run_started_at,omitempty"`
	// StateParent is the optional exact single continuous-state parent binding
	// (set/run/digest). Distinct from ParentManifests (reachability/enrich
	// heritage; digest optional there). Requires Lineage when present.
	StateParent *StateParent `json:"state_parent,omitempty"`
	// Lineage is the optional all-or-nothing continuous-lineage record.
	// Absence means pre-continuity (verified state source only — not a delta boundary).
	Lineage *LineageRecord `json:"lineage,omitempty"`
	// ParentManifests remain segment-reachability / enrich heritage references.
	// Digests stay optional. Do not auto-translate into StateParent.
	ParentManifests []ManifestReference   `json:"parent_manifests"`
	Reachability    ManifestReachability  `json:"reachability"`
	SegmentSizing   SegmentSizing         `json:"segment_sizing"`
	Coverage        []CoverageAttestation `json:"coverage"`
	Counts          ManifestCounts        `json:"counts"`
	Segments        []SegmentDescriptor   `json:"segments"`
}

type Journal struct {
	Header  JournalHeader
	Records []ObjectRecord
	Footer  JournalFooter
}

type JournalFooter struct {
	Type      string `json:"type"`
	JournalID string `json:"journal_id"`
	Records   uint64 `json:"records"`
	// ContentSHA256 is the writer-generated lowercase-hex SHA-256 over the exact
	// header line and every ordered record line (the footer line itself
	// excluded). Any post-seal mutation of the header — including its
	// crawl_prefixes provenance — or of any record, or truncation, changes the
	// recomputed digest and fails validation. Absent on legacy journals sealed
	// before content integrity; those are not tamper-evident and must not be
	// trusted as observation provenance.
	ContentSHA256 string    `json:"content_sha256,omitempty"`
	CompletedAt   time.Time `json:"completed_at"`
}

type JournalHeader struct {
	Type       string `json:"type"`
	JournalID  string `json:"journal_id"`
	IndexSetID string `json:"index_set_id"`
	RunID      string `json:"run_id"`
	Shard      string `json:"shard"`
	Scope      *Scope `json:"scope,omitempty"`
	// CrawlPrefixes records the canonical provider-key prefix plan whose complete
	// observation this journal attests. On a recovery re-publish, coverage
	// authorizes tombstones over verified-parent rows, so public Retry validates
	// its caller-supplied coverage against this recorded plan and re-publishes
	// only within the observed plan. Absent on legacy journals; recovery over
	// such a journal fails closed rather than trusting caller coverage.
	CrawlPrefixes []string `json:"crawl_prefixes,omitempty"`
	// CrawlPlanMode declares how CrawlPrefixes must be read across the sealed
	// journal set of one run, and is the discriminator recovery uses to decide
	// whether the journals it was handed are a complete observation set.
	//
	// Absent — the only form a single-lane run writes — is the legacy contract:
	// CrawlPrefixes is the whole-run plan and every journal of the run must
	// record it identically. CrawlPlanModeLaneLocal means CrawlPrefixes is only
	// the subset this journal attests, so recovery authority is the union of the
	// supplied lane plans; omitting a lane narrows that union instead of letting
	// one lane attest whole-run coverage it never listed.
	//
	// The field is additive and deliberately does not move IndexSchemaVersion. It
	// changes recovery interpretation of the multi-lane form only — object-record,
	// segment, manifest, and boundary-row schemas are untouched — and bumping the
	// shared epoch would either break the byte-identical single-lane journal or
	// force journal/manifest/hub version work. The accepted cost is a reader older
	// than lane support: handed the complete lane set it ignores this field,
	// applies its identical-plan rule to disjoint lane plans, and refuses with a
	// plan-disagreement message. That refusal is fail-closed but an imprecise
	// diagnosis, so recovery diagnostics are not forward-compatible and a pre-lane
	// reader must not be used for forward recovery. Authority still holds in such
	// a reader: handed one lane it derives only that lane-local plan, so an
	// omitted lane cannot widen coverage.
	CrawlPlanMode      string    `json:"crawl_plan_mode,omitempty"`
	IndexSchemaVersion int       `json:"index_schema_version"`
	StartedAt          time.Time `json:"started_at"`
}

type JournalSummary struct {
	Header        JournalHeader
	Footer        JournalFooter
	Records       uint64
	ContentSHA256 string
}

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

type LatestPointerReference struct {
	IndexSetID string `json:"index_set_id"`
	RunID      string `json:"run_id"`
}

type LeaseVerdict string

type LineageError struct {
	Code    string
	Message string
	// Cause is optional low-level detail (not for operator presentation).
	Cause error
}

type LineageRecord struct {
	Version    int  `json:"version"`
	Generation int  `json:"generation"`
	Baseline   bool `json:"baseline"`
}

type ManifestCounts struct {
	Rows          int `json:"rows"`
	ActiveRows    int `json:"active_rows"`
	Tombstones    int `json:"tombstones"`
	DistinctETags int `json:"distinct_etags"`
}

type ManifestReachability struct {
	Model            string `json:"model"`
	SegmentNamespace string `json:"segment_namespace"`
	RefcountMode     string `json:"refcount_mode"`
	CompactOwner     string `json:"compact_owner"`
}

type ManifestReference struct {
	IndexSetID     string `json:"index_set_id"`
	RunID          string `json:"run_id"`
	ManifestSHA256 string `json:"manifest_sha256,omitempty"`
}

type ObjectRecord struct {
	Type      string         `json:"type"`
	JournalID string         `json:"journal_id"`
	Sequence  uint64         `json:"sequence"`
	Op        ObjectRecordOp `json:"op"`

	RelKey       string     `json:"rel_key"`
	ObservedAt   time.Time  `json:"observed_at"`
	SizeBytes    *int64     `json:"size_bytes,omitempty"`
	ETag         string     `json:"etag,omitempty"`
	LastModified *time.Time `json:"last_modified,omitempty"`
	StorageClass *string    `json:"storage_class,omitempty"`

	ContentType    *string    `json:"content_type,omitempty"`
	ArchiveStatus  *string    `json:"archive_status,omitempty"`
	RestoreState   *string    `json:"restore_state,omitempty"`
	RestoreExpiry  *time.Time `json:"restore_expiry,omitempty"`
	HeadEnrichedAt *time.Time `json:"head_enriched_at,omitempty"`
}

type ObjectRecordOp string

type OnSegmentProgressFunc func(progress SegmentProgress)

type OrderedRowSource interface {
	Next(ctx context.Context) (CurrentObjectRow, error)
	Close() error
}

type ParentReaderCategory string

type ParentReaderError struct {
	Category ParentReaderCategory
	Phase    string
	Message  string
	// contains filtered or unexported fields
}

type ParentRowSource interface {
	Next(ctx context.Context) (CurrentObjectRow, error)
	Close() error
}

type PublicationMode string

type PublishConfig struct {
	IndexSetID        string
	RunID             string
	RunStartedAt      time.Time
	ManifestCreatedAt time.Time
	// SnapshotCompletionClock is sampled immediately before the immutable
	// complete marker commit, after the manifest and referenced segments have
	// been written and verified. Nil uses the UTC wall clock.
	SnapshotCompletionClock func() time.Time
	ParentManifests         []ManifestReference
	// PriorRows seeds prior current-state when no ParentSource is supplied (the
	// slice adapter path, used by enrich and tests). When ParentSource is set it
	// takes precedence and PriorRows is ignored.
	PriorRows []CurrentObjectRow
	// ParentSource, when non-nil, streams the verified parent's current-state rows
	// into the compaction merge without materializing them. Continuity activation
	// passes a bounded reader over the verified parent snapshot here.
	ParentSource ParentRowSource
	// StateParent and Lineage are the digest-bound continuity metadata written
	// into the published manifest. Nil on a legacy/baseline-free publication.
	StateParent          *StateParent
	Lineage              *LineageRecord
	JournalPaths         []string
	Coverage             []CoverageAttestation
	SegmentDir           string
	ManifestPath         string
	CompletePath         string
	LatestPath           string
	TargetRowsPerSegment int
	// SpillRoot is the operator-controlled directory under which the streaming
	// current-state merge stages its owner-only, symlink-safe workspace. When
	// empty it defaults to a "spillmerge" directory beside the sealed journals
	// (which are already resolved through operator app-data path classes).
	SpillRoot string
	// SpillBudget bounds the streaming merge's memory, workspace disk, and merge
	// topology. Zero fields fall back to DefaultSpillMergeBudget.
	SpillBudget SpillMergeBudget
	// Mode selects compaction/publication policy (default crawl vs enrich-only).
	Mode PublicationMode
	// ExpectedParent, when non-nil, enforces latest-pointer CAS at advance.
	// First publication of a set may leave this nil. Required for enrich-only.
	ExpectedParent *ExpectedParentToken
	// WriteLease is required for any latest advance. Must be a held package-owned
	// *WriteLease (not an external interface). Nil or released leases fail closed.
	WriteLease *WriteLease
	AfterStep  func(PublishStep) error
	// OnSegmentProgress is optional observational segment-write progress
	// (counts only). Outside persisted artifacts; never a publish failure vector.
	OnSegmentProgress OnSegmentProgressFunc
}

type PublishResult struct {
	Journals   []JournalSummary
	Compaction CompactionResult
	Manifest   InternalManifest
	// ManifestSHA256 is the digest of the committed manifest bytes (same value
	// written into complete.json). Prefer this over re-hashing after publish.
	ManifestSHA256 string
	// SnapshotCompletedAt is the exact local complete-marker commit time.
	SnapshotCompletedAt time.Time
	// LatestAdvanced is true after latest.json was successfully written.
	// Callers must treat this as committed even if a later post-advance hook fails.
	LatestAdvanced bool
}

type PublishStep string

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

type PublishedRunLookup func(indexSetID, runID string) (completePath string, err error)

type PublishedSnapshot struct {
	LatestPath string
	// CompletePath is the complete marker path used for this open when known.
	CompletePath string
	// CompleteSHA256 binds the exact complete-marker bytes parsed for this open.
	CompleteSHA256 string
	Complete       publishedCompleteDoc
	Manifest       InternalManifest
	SegmentDir     string
	// AccountedMarkerBytes / AccountedManifestBytes are the exact on-disk byte
	// lengths of the complete marker and manifest slices that were digested and
	// parsed for this open (same-bytes trust). Used by ancestry aggregate budgets.
	AccountedMarkerBytes   int64
	AccountedManifestBytes int64
}

type ReachabilityInput struct {
	Manifests         []InternalManifest
	RetainedManifests []ManifestReference
	LatestPointers    []LatestPointerReference
}

type ReachabilityPlan struct {
	ReachableSegments []ReachableSegment `json:"reachable_segments"`
	DerivedRefcounts  []DerivedRefcount  `json:"derived_refcounts"`
}

type ReachableSegment struct {
	SegmentID      string              `json:"segment_id"`
	Path           string              `json:"path"`
	Digest         SegmentDigest       `json:"digest"`
	ReferencedBy   []ManifestReference `json:"referenced_by"`
	ReferenceCount int                 `json:"reference_count"`
}

type ReclaimResult struct {
	IndexSetID string
	Path       string
	Verdict    LeaseVerdict
	// Reclaimed is true only when a provably-unheld lock file was removed.
	Reclaimed bool
	// Holder is attribution copied from the on-disk doc before any action.
	Holder string
}

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

type SegmentDescriptor struct {
	SegmentID     string        `json:"segment_id"`
	Path          string        `json:"path"`
	Format        string        `json:"format"`
	Compression   string        `json:"compression"`
	Rows          int           `json:"rows"`
	Tombstones    int           `json:"tombstones"`
	SizeBytes     int64         `json:"size_bytes"`
	MinRelKey     string        `json:"min_rel_key,omitempty"`
	MaxRelKey     string        `json:"max_rel_key,omitempty"`
	DistinctETags int           `json:"distinct_etags"`
	Digest        SegmentDigest `json:"digest"`
}

type SegmentDigest struct {
	Algorithm string `json:"algorithm"`
	Hex       string `json:"hex"`
}

type SegmentProgress struct {
	Segment  int // 1-based index of the segment just written
	Total    int // planned segment count for this write
	Rows     int // rows in the segment just written
	RowsDone int // cumulative rows written across segments so far
}

type SegmentSizing struct {
	TargetRowsPerSegment int    `json:"target_rows_per_segment"`
	Rationale            string `json:"rationale"`
}

type SegmentWriterConfig struct {
	Dir                    string
	IndexSetID             string
	RunID                  string
	CreatedAt              time.Time
	TargetRowsPerSegment   int
	AllowExistingIdentical bool
	ParentManifests        []ManifestReference
	Coverage               []CoverageAttestation
	// Continuity lineage inputs supplied by the durable build path: ordinary
	// builds set these from the verified parent capture (a first publication
	// emits a baseline lineage record with no state parent).
	RunStartedAt *time.Time
	StateParent  *StateParent
	Lineage      *LineageRecord
	// OnSegmentProgress is optional. Invoked after each segment file is written;
	// outside persisted artifact bytes and ignored for failure control.
	OnSegmentProgress OnSegmentProgressFunc
	// contains filtered or unexported fields
}

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

type SetAuthorityLease struct {
	IndexSetID string
	Path       string
	Verdict    LeaseVerdict
	Holder     string
	AcquiredAt time.Time
	DocType    string
	ModTime    time.Time
	// Detail carries the reason for an invalid/indeterminate verdict, or an
	// attribution note. It never affects the verdict.
	Detail string
}

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

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

type SpillMergeBudget struct {
	MaxBufferedRows   int
	MaxBufferedBytes  int64
	MaxRecordBytes    int64
	MaxJournalSources int
	MaxWorkspaceBytes int64
	MaxSpillRuns      int
	MaxFanIn          int
	MaxMergePasses    int
}

type SpillMergeCategory string

type SpillMergeConfig struct {
	IndexSetID   string
	RunID        string
	RunStartedAt time.Time
	Parent       ParentRowSource
	JournalPaths []string
	Coverage     []CoverageAttestation
	Mode         PublicationMode
	// SpillRoot is an explicit operator-controlled directory. Required.
	SpillRoot string
	Budget    SpillMergeBudget
}

type SpillMergeError struct {
	Category  SpillMergeCategory
	Phase     string
	Message   string
	AttemptID string
	Cause     error
}

type SpillMergeStats struct {
	ObservedRecords    int
	EnrichmentRecords  int
	EmittedRows        int
	NewTombstones      int
	PeakBufferedRows   int
	PeakBufferedBytes  int64
	PeakWorkspaceBytes int64
	SpillRunCount      int
	MergePasses        int
	PeakOpenFiles      int
	Complete           bool
}

type StateParent struct {
	IndexSetID     string `json:"index_set_id"`
	RunID          string `json:"run_id"`
	ManifestSHA256 string `json:"manifest_sha256"`
}

type StreamSegmentCategory string

type StreamSegmentError struct {
	Category StreamSegmentCategory
	Phase    string
	Message  string
	// RowIndex is 1-based for row-phase failures; zero when not applicable.
	RowIndex int
	Cause    error
}

type Tombstone struct {
	IndexSetID string
	RelKey     string
	RunID      string
	DeletedAt  time.Time
}

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

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