store

package
v0.14.0 Latest Latest
Warning

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

 Go to latest Published: Aug 23, 2026 License: Apache-2.0 Imports: 37 Imported by: 0

Documentation

Overview

Package store implements the SQLite-backed virtual tree.

Index

Constants

View Source 
const (
	ExtractionOK     = "ok"
	ExtractionFailed = "failed"
)
View Source 
const (
	SearchMatchName    = "name"
	SearchMatchContent = "content"
)
View Source 
const (
	// MaxWalkPageSize bounds every store-level snapshot page.
	MaxWalkPageSize = 5000
	// MaxWalkDepth bounds the indexed frontier expansion required by one walk.
	MaxWalkDepth = 256
	// MaxWalkPathBytes bounds each path materialized in a walk page. At the
	// maximum page size, paths consume at most about 80 MiB before node data.
	MaxWalkPathBytes = 16 << 10
)
View Source 
const MaxAuditEvidenceScopes = 1000

MaxAuditEvidenceScopes bounds caller-supplied prefix work independently of the HTTP body limit. Enrollment enforces the same limit so every valid vault can produce a terminal evidence bundle.

View Source 
const MaxBatchMoves = 1000

MaxBatchMoves bounds one atomic reorganization and its response.

View Source 
const MaxProvenancePageSize = 1000
View Source 
const MaxVersionPruneIDs = 1000

MaxVersionPruneIDs bounds explicit point selections. Larger history cleanup should use an age, count, or all-prior selector instead of holding a write transaction for an unbounded request body.

View Source 
const UnconditionalRev int64 = -1

UnconditionalRev is the only ifRev value that skips the revision precondition on Move, Trash, and Restore. Every other value — including other negatives, which can never match a real revision — must satisfy the check, so an accidentally propagated bad revision fails stale instead of silently mutating.

Variables

View Source 
var (
	// ErrNotFound is returned when a node, path, or blob does not exist.
	ErrNotFound = errors.New("not found")
	// ErrExists is returned when a live sibling with the same name exists.
	ErrExists = errors.New("name already exists")
	// ErrNotDir is returned when a directory operation targets a file.
	ErrNotDir = errors.New("not a directory")
	// ErrNotFile is returned when a file operation targets a directory.
	ErrNotFile = errors.New("not a file")
	// ErrCycle is returned when a move would place a node under its own descendant.
	ErrCycle = errors.New("move would create a cycle")
	// ErrInvalidName is returned for empty, ".", "..", or names containing '/' or NUL.
	ErrInvalidName = errors.New("invalid name")
	// ErrInvalidTag is returned for an empty, non-UTF-8, or control-containing tag name.
	ErrInvalidTag = errors.New("invalid tag name")
	// ErrNotTrashed is returned when restoring a node that is not a trash root.
	ErrNotTrashed = errors.New("node is not trashed")
	// ErrIsRoot is returned when an operation targets the root node.
	ErrIsRoot = errors.New("operation not allowed on root")
	// ErrStaleRevision means a mutation's expected revision no longer
	// matches the node (lost-update guard for If-Match).
	ErrStaleRevision = errors.New("revision mismatch")
	// ErrVersionNodeMismatch means a requested source version belongs to a
	// different stable file node.
	ErrVersionNodeMismatch = errors.New("content version belongs to another node")
	// ErrVersionAlreadyCurrent means a revert selected the node's current head,
	// which is not a historical transition.
	ErrVersionAlreadyCurrent = errors.New("content version is already current")
	// ErrProvenanceMismatch means an immutable retry named source evidence
	// that is not an active fact on the existing document.
	ErrProvenanceMismatch = errors.New("provenance does not match existing content")
	// ErrInvalidVersionPrune means a history-pruning selector is absent,
	// contradictory, or otherwise unsafe to execute.
	ErrInvalidVersionPrune = errors.New("invalid version-prune selector")
	// ErrInvalidBatchMove means a batch is empty, oversized, repeats a source,
	// or does not identify each source in exactly one supported way.
	ErrInvalidBatchMove = errors.New("invalid batch move")
	// ErrAuditMutationUnsupported means an audited vault cannot perform a
	// logical mutation until that mutation records its audit transition.
	ErrAuditMutationUnsupported = errors.New("mutation is not supported for an audited vault")
	// ErrAuditAlreadyEnabled means a plan reviewed against dormant authority
	// cannot run because another operation enabled audit first.
	ErrAuditAlreadyEnabled = errors.New("audit is already enabled for this vault")
	// ErrAuditScopeOverlap means an additional scope would share at least one
	// sticky member with an existing scope. Disjoint scopes are supported first;
	// overlapping and nested scopes remain fail-closed.
	ErrAuditScopeOverlap = errors.New("audit scope overlaps existing permanent protection")
	// ErrAuditScopeLimit means permanent enrollment has reached the maximum
	// number of scope terminals one evidence bundle can represent.
	ErrAuditScopeLimit = errors.New("audit scope limit reached")
	// ErrAuditPreviewStale means enrollment no longer matches the exact
	// metadata state reviewed by the caller.
	ErrAuditPreviewStale = errors.New("audit enrollment preview is stale")
	// ErrAuditNotEnrolled means a node exists but has no sticky audit membership.
	ErrAuditNotEnrolled = errors.New("node is not enrolled in an audit scope")
	// ErrInvalidAuditCursor means an audit-history cursor is malformed or belongs
	// to a different stable node or scope.
	ErrInvalidAuditCursor = errors.New("invalid audit history cursor")
	// ErrBlobStorePrimary means an operation would detach, drain, or remove the
	// fixed built-in primary.
	ErrBlobStorePrimary = errors.New("operation not allowed on primary blob store")
	// ErrBlobStoreNotEmpty means a store still carries physical authority.
	ErrBlobStoreNotEmpty = errors.New("blob store still contains authoritative locations")
	// ErrBlobStoreState means the requested lifecycle transition is invalid.
	ErrBlobStoreState = errors.New("invalid blob-store lifecycle transition")
	// ErrStorageOperationTerminal means a completed, failed, or cancelled
	// operation can no longer accept cancellation or progress.
	ErrStorageOperationTerminal = errors.New("storage operation is already terminal")
)
View Source 
var ErrPhysicalAuthorityMissing = packstore.ErrPhysicalAuthorityMissing

ErrPhysicalAuthorityMissing means logical blob membership exists but no indexed loose representation or pack mapping currently authorizes reads.

View Source 
var ErrStorageOperationCancelled = errors.New("storage operation cancellation was requested")

Functions

func DefaultSQLiteDriver 

func DefaultSQLiteDriver() docsqlite.Driver

DefaultSQLiteDriver returns the build's standalone-compatible adapter: CGO builds use mattn/go-sqlite3 and no-CGO builds use modernc.org/sqlite.

func NormalizeName 

func NormalizeName(name string) (string, error)

NormalizeName NFC-normalizes name and validates it for use as a node name. Names are stored as given (post-NFC) and compared case-sensitively.

func NormalizeSearchMIMEType added in v0.11.0 

func NormalizeSearchMIMEType(value string) (string, error)

NormalizeSearchMIMEType accepts one parameter-free media type and returns its canonical base spelling. Stored parameters do not participate in search filtering because they describe representation details, not the format.

func NormalizeSearchTimeBounds added in v0.11.0 

func NormalizeSearchTimeBounds(modifiedSince, modifiedBefore string) (string, string, error)

NormalizeSearchTimeBounds accepts optional absolute RFC3339 timestamps and returns canonical UTC bounds. The half-open interval makes adjacent searches compose without duplicate boundary results.

func NormalizeTagName 

func NormalizeTagName(name string) (string, error)

NormalizeTagName validates and NFC-normalizes a user-facing tag name. Names are compared case-sensitively and may contain spaces or '/'.

func ValidateAuditEvidence 

func ValidateAuditEvidence(evidence AuditEvidence) error

ValidateAuditEvidence rejects evidence that cannot represent a terminal allocation lineage plus a stable, sorted set of scope terminals.

func ValidateAuditHistoryCursor 

func ValidateAuditHistoryCursor(raw string, nodeID int64) error

ValidateAuditHistoryCursor checks that an opaque cursor belongs to nodeID.

func ValidateAuditPathState 

func ValidateAuditPathState(path, state string) error

ValidateAuditPathState checks the canonical coordinate domain used by an audit path event. It deliberately does not use host-filesystem path rules.

func ValidateAuditScopeHistoryCursor added in v0.10.1 

func ValidateAuditScopeHistoryCursor(raw, scopeID string) error

ValidateAuditScopeHistoryCursor checks that an opaque cursor belongs to scopeID.

func ValidatePlacementPlan added in v0.12.0 

func ValidatePlacementPlan(plan PlacementPlan) error

func ValidateSecondaryBlobStoreName added in v0.12.0 

func ValidateSecondaryBlobStoreName(name string) error

ValidateSecondaryBlobStoreName rejects names that cannot coexist with the fixed built-in primary. Callers use it before touching an external namespace.

func ValidateStorageRecoveryPlan added in v0.12.0 

func ValidateStorageRecoveryPlan(plan StorageRecoveryPlan) error

func ValidateVersionPruneSelector 

func ValidateVersionPruneSelector(selector VersionPruneSelector) error

ValidateVersionPruneSelector applies the authoritative store-level selector rules. HTTP and CLI adapters translate their inputs into this type and reuse the same validation before opening a transaction.

Types

type AuditAttachmentChange 

type AuditAttachmentChange struct {
	Kind     string
	Identity AuditAttachmentIdentity
	Before   *AuditAttachmentState
	After    *AuditAttachmentState
}

AuditAttachmentChange makes tag and provenance events self-explanatory.

type AuditAttachmentIdentity 

type AuditAttachmentIdentity struct {
	TagID        string
	NodeID       int64
	ProvenanceID string
}

AuditAttachmentIdentity identifies one tag or provenance record without relying on its mutable display fields.

type AuditAttachmentState 

type AuditAttachmentState struct {
	TagID         string
	NodeID        int64
	TagName       string
	ProvenanceID  string
	IngestID      string
	OriginalPath  *string
	OriginalMTime *string
	Supersedes    *string
}

AuditAttachmentState is the typed before/after state of one attached record. The enclosing change Kind determines which fields are present.

type AuditEnrollmentPlan 

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

AuditEnrollmentPlan carries the server-private, non-derivable inputs behind a preview. Its fields are intentionally opaque outside this package: callers may present the summary, but only Store can execute the exact plan.

func (*AuditEnrollmentPlan) Preview 

func (plan *AuditEnrollmentPlan) Preview() AuditEnrollmentPreview

Preview returns a copy of the plan's public retention inventory.

type AuditEnrollmentPreview 

type AuditEnrollmentPreview struct {
	InitialAuthority       bool
	VaultID                string
	ScopeID                string
	OperationID            string
	TargetNodeID           int64
	TargetPath             string
	BaselineDigest         string
	MemberCount            int
	FileCount              int
	DirectoryCount         int
	VersionCount           int
	LogicalVersionBytes    int64
	UniqueBlobs            int
	UniqueBlobBytes        int64
	UnresolvedTrashOrigins int
	VaultTopologyNodes     int
	VaultAttachmentRecords int
	AuthorityJSONBytes     int64
}

AuditEnrollmentPreview is the exact retention boundary a caller reviews before permanently enabling one audit scope in a vault.

type AuditEvent 

type AuditEvent struct {
	ID                        string
	OperationID               string
	OperationSequence         int64
	Ordinal                   int64
	NodeID                    int64
	Kind                      string
	ScopeID                   string
	RecordedAt                string
	Origin                    string
	AgentLabel                *string
	PriorNodeRevision         int64
	ResultingNodeRevision     int64
	PriorCurrentVersionID     *string
	ResultingCurrentVersionID *string
	SourceVersionID           *string
	TargetNodeID              *int64
	BaselineDigest            *string
	Attachment                *AuditAttachmentChange
	OldPath                   *AuditPathState
	NewPath                   *AuditPathState
}

AuditEvent is one canonical node event projected for human and agent readers.

type AuditEventPage 

type AuditEventPage struct {
	Node       Node
	Path       string
	Items      []AuditEvent
	Total      int
	Limit      int
	Cursor     string
	NextCursor string
}

AuditEventPage is a stable newest-first page for one audited node.

type AuditEvidence 

type AuditEvidence struct {
	Enabled                    bool
	VaultID                    string
	LineageID                  string
	OperationSequenceHighWater int64
	AllocationEntryCount       int64
	AllocationHead             string
	Scopes                     []AuditScopeEvidence
}

AuditEvidence is the stable authority bundle produced after replay.

type AuditEvidenceCheck 

type AuditEvidenceCheck struct {
	Extends  bool
	Problems []AuditEvidenceProblem
}

AuditEvidenceCheck is the exact-prefix proof for externally recorded audit evidence. Extends is true exactly when Problems is empty.

type AuditEvidenceProblem 

type AuditEvidenceProblem struct {
	Code    string
	ScopeID string
	Message string
}

AuditEvidenceProblem explains why current authority does not extend one externally recorded evidence bundle.

type AuditMembershipStatus 

type AuditMembershipStatus struct {
	NodeID          int64
	Path            string
	Trashed         bool
	Protected       bool
	ScopeIDs        []string
	BaselineDigests []string
}

AuditMembershipStatus explains whether one inspected node is protected and which permanent scope/baseline bindings provide that protection.

type AuditPathState 

type AuditPathState struct {
	Path  string
	State string
}

AuditPathState preserves both the canonical coordinate and its domain.

type AuditScopeEventPage added in v0.10.1 

type AuditScopeEventPage struct {
	Scope      AuditScopeStatus
	Items      []AuditEvent
	Total      int
	Limit      int
	Cursor     string
	NextCursor string
}

AuditScopeEventPage is a stable newest-first page across one audit scope.

type AuditScopeEvidence 

type AuditScopeEvidence struct {
	ID         string
	EntryCount int64
	ChainHead  string
}

AuditScopeEvidence is one verified scope-chain terminal.

type AuditScopeStatus 

type AuditScopeStatus struct {
	ID                string
	TargetNodeID      int64
	TargetPath        string
	TargetTrashed     bool
	EnableOperationID string
	BaselineDigest    string
	MemberCount       int
	EntryCount        int64
	ChainHead         string
}

AuditScopeStatus is one permanent scope and its current chain evidence.

type AuditStatus 

type AuditStatus struct {
	Enabled                    bool
	EnabledScopeID             string
	VaultID                    string
	LineageID                  string
	OperationSequenceHighWater int64
	AllocationEntryCount       int64
	AllocationHead             string
	Scopes                     []AuditScopeStatus
	Membership                 *AuditMembershipStatus
}

AuditStatus is the vault-wide audit authority plus optional node membership.

type AuditVerification 

type AuditVerification struct {
	Evidence       AuditEvidence
	EvidenceCheck  *AuditEvidenceCheck
	ProtectedBlobs []BlobInfo
	ProtectedBytes int64 // unique raw bytes across ProtectedBlobs
}

AuditVerification is one independently replayed audit snapshot plus the unique blobs whose bytes permanent history requires.

type BatchMoveRequest added in v0.10.1 

type BatchMoveRequest struct {
	SourcePath      string
	NodeID          int64
	IfRevision      int64
	DestinationPath string
}

BatchMoveRequest identifies a live source either by SourcePath or by the stable NodeID plus IfRevision, and gives its absolute final destination.

type BatchMoveResult added in v0.10.1 

type BatchMoveResult struct {
	Node     Node
	FromPath string
	Path     string
}

BatchMoveResult is the transactionally captured receipt for one request.

type BlobInfo 

type BlobInfo struct {
	Hash string
	Size int64
}

BlobInfo identifies a recorded blob.

type BlobLocation added in v0.12.0 

type BlobLocation struct {
	Hash         string
	StoreID      string
	Generation   string
	Kind         string
	Encoding     string
	LogicalSize  int64
	StoredSize   int64
	PackEligible bool
	Pack         *PackedLocation
}

BlobLocation is one catalog-authorized physical representation.

type BlobPhysical added in v0.10.0 

type BlobPhysical struct {
	Encoding     string
	StoredBytes  int64
	PackEligible bool
	// Created proves this write published a new, fully hashed canonical loose
	// representation rather than deduplicating an existing file by type and size.
	Created bool
}

BlobPhysical is the loose representation published before a metadata transaction grants logical authority.

type BlobStore added in v0.12.0 

type BlobStore struct {
	ID             string
	Name           string
	Kind           string
	Role           string
	Lifecycle      string
	Binding        string
	OwnershipEpoch string
	CreatedAt      time.Time
}

BlobStore is one stable physical-store identity in the local placement catalog. Binding names refer to machine-local configuration; their resolved paths or credentials never enter SQLite.

type BlobStoreEvacuationFinalization added in v0.12.0 

type BlobStoreEvacuationFinalization struct {
	Retire           []packstore.ObjectRef
	RevokedLocations int64
	Detached         bool
}

BlobStoreEvacuationFinalization is the catalog result of revoking an empty source after every location has verified destination coverage. Physical retirement happens afterward through Kit's reader-safe backend.

type BlobStoreStats added in v0.12.0 

type BlobStoreStats struct {
	AuthoritativeObjects int64
	LogicalBytes         int64
	StoredBytes          int64
	PackCount            int64
	DeadPackedBytes      int64
	SoleAuthorityObjects int64
	AffectedDocuments    int64
}

BlobStoreStats reports catalog-authorized physical inventory for one store.

type ContentReference 

type ContentReference struct {
	Version   ContentVersion
	Node      Node
	Path      string
	IsCurrent bool
}

ContentReference joins one immutable content version to the stable node that retains it. Path is populated only for a live node; trashed nodes deliberately have no resolvable virtual path.

type ContentVersion 

type ContentVersion struct {
	ID                    string
	NodeID                int64
	BlobHash              string
	Size                  int64
	MimeType              string
	RecordedAt            string
	NodeRevision          int64
	IntroducedOperationID string
	TransitionKind        string
	SourceVersionID       *string
}

ContentVersion is one immutable byte identity recorded for a stable file node. Initial ingest creates content_create records, verified replacement adds content_replace heads, and reversion adds content_revert heads that retain their source identity.

type ContentVersionView added in v0.12.0 

type ContentVersionView struct {
	Node    Node
	Version ContentVersion
}

ContentVersionView binds a file node and one of its retained versions to the same read snapshot.

type ContentWriteReceipt added in v0.10.0 

type ContentWriteReceipt struct {
	Node     Node
	Version  ContentVersion
	Physical PhysicalContent
}

ContentWriteReceipt captures content authority from the transaction that created or replaced a file. Callers need no fallible post-commit reads.

type DirectoryPageView added in v0.11.0 

type DirectoryPageView struct {
	Directory NodeView
	Children  []Node
	Total     int
}

DirectoryPageView binds a live directory and one child page to the same read snapshot. Callers can render child paths without combining directory authority from one point in time with children from another.

type ExtractionCandidate 

type ExtractionCandidate struct {
	BlobHash string
	Size     int64
}

ExtractionCandidate is one catalog-authorized text blob that has not been processed by the current extractor version.

type ExtractionResult 

type ExtractionResult struct {
	BlobHash         string
	Extractor        string
	ExtractorVersion int64
	Status           string
	Error            string
	Text             string
}

ExtractionResult is one complete, versioned derived-text attempt. Text is present only for a successful, terminally verified extraction.

type GCCandidate added in v0.10.0 

type GCCandidate struct {
	Hash            string
	Loose           bool
	LooseStoredSize int64
}

GCCandidate is one unreachable catalog row and its indexed loose authority.

type GCCandidateScanPage added in v0.10.0 

type GCCandidateScanPage struct {
	Items     []GCCandidate
	Examined  int
	HighWater string
	More      bool
}

GCCandidateScanPage reports bounded raw catalog progress independently of how many rows qualify as unreachable work.

type IngestRun 

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

IngestRun identifies one logical import and carries the immutable metadata that is published with its first imported file. Holding a run grants no metadata authority by itself.

func (IngestRun) ID 

func (r IngestRun) ID() string

ID returns the stable ingest identity.

type LooseBacklog added in v0.10.0 

type LooseBacklog struct {
	EligibleObjects     int64
	EligibleBytes       int64
	EligibleStoredBytes int64
	RawObjects          int64
	CompressedObjects   int64
}

LooseBacklog summarizes loose content eligible for an explicit pack pass.

type MetadataSnapshot 

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

MetadataSnapshot owns a dedicated deferred read transaction. Store's normal connections use BEGIN IMMEDIATE for mutations; using that pool here would hold the writer lock for the full backup instead of only pinning a WAL view.

func (*MetadataSnapshot) Close 

func (s *MetadataSnapshot) Close() error

func (*MetadataSnapshot) Export 

func (s *MetadataSnapshot) Export(ctx context.Context, w io.Writer) error

Export writes the deterministic logical metadata held by this snapshot.

func (*MetadataSnapshot) QueryContext 

func (s *MetadataSnapshot) QueryContext(
	ctx context.Context, query string, args ...any,
) (*sql.Rows, error)

func (*MetadataSnapshot) QueryRowContext 

func (s *MetadataSnapshot) QueryRowContext(
	ctx context.Context, query string, args ...any,
) *sql.Row

type Node 

type Node struct {
	ID               int64
	ParentID         *int64
	Name             string
	Kind             string // "dir" | "file"
	CurrentVersionID string
	BlobHash         string
	Size             int64
	MimeType         string
	Revision         int64
	CreatedAt        string
	ModifiedAt       string
	TrashedAt        *string
}

Node is a row of the virtual tree. IDs are canonical; paths are display.

func (Node) IsDir 

func (n Node) IsDir() bool

IsDir reports whether the node is a directory.

type NodeProvenancePage added in v0.11.0 

type NodeProvenancePage struct {
	Node   Node
	Path   string
	Items  []ProvenanceFact
	Total  int
	Limit  int
	Offset int
}

NodeProvenancePage is one transactionally consistent document and bounded page of its newest-ingest-first provenance facts. Path is empty for trash.

type NodeView added in v0.11.0 

type NodeView struct {
	Node Node
	Path string
}

NodeView binds one node snapshot to its live canonical path. Path is empty when the snapshot marks the node as trashed.

type PackCatalog 

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

PackCatalog adapts docbank's blob membership and physical metadata to Kit's application-neutral storage engine. A blobs row establishes logical membership; indexed loose state or a pack mapping separately grants read authority. Nodes, versions, and future external pins decide whether GC may remove logical membership.

func NewPackCatalog 

func NewPackCatalog(s *Store) *PackCatalog

NewPackCatalog constructs a packed-storage catalog over s.

func (*PackCatalog) AdoptPack 

func (c *PackCatalog) AdoptPack(ctx context.Context, record packstore.PackRecord, adoptions []packstore.Adoption) error

func (*PackCatalog) ClearPackMetadata 

func (c *PackCatalog) ClearPackMetadata(ctx context.Context) error

func (*PackCatalog) CommitRepack 

func (c *PackCatalog) CommitRepack(ctx context.Context, sourceIDs []string,
	records []packstore.PackRecord, moves []packstore.RepackMove) error

func (*PackCatalog) DeleteEmptyPackRecord 

func (c *PackCatalog) DeleteEmptyPackRecord(ctx context.Context, packID string) (bool, error)

func (*PackCatalog) DeleteIndexEntry 

func (c *PackCatalog) DeleteIndexEntry(ctx context.Context, hash packstore.Hash) error

func (*PackCatalog) DeletePackRecord 

func (c *PackCatalog) DeletePackRecord(ctx context.Context, packID string) error

func (*PackCatalog) HasPackRecord 

func (c *PackCatalog) HasPackRecord(ctx context.Context, packID string) (bool, error)

func (*PackCatalog) ListIndexed 

func (c *PackCatalog) ListIndexed(ctx context.Context) ([]packstore.IndexEntry, error)

func (*PackCatalog) ListLivePackEntries 

func (c *PackCatalog) ListLivePackEntries(ctx context.Context, packID string) ([]packstore.IndexEntry, error)

func (*PackCatalog) ListPackEntries 

func (c *PackCatalog) ListPackEntries(ctx context.Context, packID string) ([]packstore.IndexEntry, error)

func (*PackCatalog) ListPackRecords 

func (c *PackCatalog) ListPackRecords(ctx context.Context) ([]packstore.PackRecord, error)

func (*PackCatalog) ListPackUsage 

func (c *PackCatalog) ListPackUsage(ctx context.Context) ([]packstore.PackUsage, error)

func (*PackCatalog) ListReferences 

func (c *PackCatalog) ListReferences(ctx context.Context) (packstore.ReferenceInventory, error)

func (*PackCatalog) ListUnpacked 

func (c *PackCatalog) ListUnpacked(ctx context.Context) ([]packstore.Candidate, error)

func (*PackCatalog) PrimaryOwnership added in v0.12.0 

func (c *PackCatalog) PrimaryOwnership() packstore.Ownership

PrimaryOwnership is the fixed local namespace identity. Unlike secondary bindings its location is implicit in the vault, but Kit still uses the marker to fence destructive physical work.

func (*PackCatalog) PrimaryStoreID added in v0.12.0 

func (c *PackCatalog) PrimaryStoreID() packstore.StoreID

PrimaryStoreID identifies the built-in filesystem backend.

func (*PackCatalog) PruneUnreferenced 

func (c *PackCatalog) PruneUnreferenced(ctx context.Context) (int64, error)

func (*PackCatalog) RecordPack 

func (c *PackCatalog) RecordPack(ctx context.Context, record packstore.PackRecord, adoptions []packstore.Adoption) error

func (*PackCatalog) Resolve 

func (c *PackCatalog) Resolve(ctx context.Context, hash packstore.Hash) (packstore.Location, error)

func (*PackCatalog) ResolveLocations added in v0.12.0 

func (c *PackCatalog) ResolveLocations(
	ctx context.Context, hash packstore.Hash,
) (packstore.Resolution, error)

ResolveLocations exposes the store-scoped physical authority used by Kit's multi-location reader. Maintenance still uses the released single-layout Catalog surface as a thin adapter over the same rows.

type PackRestoreCatalog 

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

PackRestoreCatalog grants packed authority in an unpublished restored database. It deliberately accepts a *sql.DB rather than a Store because Kit owns the staged database lifecycle until restore publication.

func NewPackRestoreCatalog 

func NewPackRestoreCatalog(db *sql.DB) *PackRestoreCatalog

NewPackRestoreCatalog constructs a restore-only packed catalog over db.

func (*PackRestoreCatalog) ReplaceRestoredPacks 

func (c *PackRestoreCatalog) ReplaceRestoredPacks(
	ctx context.Context, records []packstore.PackRecord, adoptions []packstore.Adoption,
) error

ReplaceRestoredPacks atomically discards pack metadata captured from the source vault and grants authority only to packs Kit published and verified in the restore target.

type PackedLocation added in v0.12.0 

type PackedLocation struct {
	PackID string
	Offset int64
	Stored int64
	Raw    int64
	Flags  uint8
	CRC32C uint32
}

PackedLocation is the store-scoped immutable pack entry for one blob.

type PhysicalContent added in v0.10.0 

type PhysicalContent struct {
	Kind         string
	Encoding     string
	LogicalBytes int64
	StoredBytes  int64
	PackEligible bool
}

PhysicalContent describes the catalog-authorized representation of one logical blob without requiring a filesystem scan.

type PlacementCommit added in v0.12.0 

type PlacementCommit struct {
	DestinationAuthorized bool                 `json:"destination_authorized"`
	SourceRevoked         bool                 `json:"source_revoked"`
	ReferenceDrift        bool                 `json:"reference_drift"`
	AuditPinned           bool                 `json:"audit_pinned"`
	PackRepackRequired    bool                 `json:"pack_repack_required"`
	Retire                *packstore.ObjectRef `json:"-"`
}

type PlacementHash added in v0.12.0 

type PlacementHash struct {
	Hash                string                  `json:"hash"`
	Size                int64                   `json:"size"`
	SelectedReferences  int64                   `json:"selected_references"`
	TotalReferences     int64                   `json:"total_references"`
	Source              packstore.ReadLocation  `json:"source"`
	Destination         *packstore.ReadLocation `json:"destination,omitempty"`
	SharedReference     bool                    `json:"shared_reference"`
	AuditPinned         bool                    `json:"audit_pinned"`
	RetireSource        bool                    `json:"retire_source"`
	PackRepackRequired  bool                    `json:"pack_repack_required"`
	UnavailableAtSource bool                    `json:"unavailable_at_source"`
	ScratchBytes        int64                   `json:"scratch_bytes,omitzero"`
}

type PlacementPlan added in v0.12.0 

type PlacementPlan struct {
	Version             int              `json:"version"`
	Request             PlacementRequest `json:"request"`
	Digest              string           `json:"digest"`
	Hashes              []PlacementHash  `json:"hashes"`
	SelectedNodes       int64            `json:"selected_nodes"`
	SelectedVersions    int64            `json:"selected_versions"`
	LogicalBytes        int64            `json:"logical_bytes"`
	TransferBytes       int64            `json:"transfer_bytes"`
	ReadBackBytes       int64            `json:"read_back_bytes"`
	RemoteEgressBytes   int64            `json:"remote_egress_bytes"`
	ScratchBytes        int64            `json:"scratch_bytes"`
	AlreadyPresentBytes int64            `json:"already_present_bytes"`
	RetirableBytes      int64            `json:"retirable_bytes"`
	SharedBytes         int64            `json:"shared_bytes"`
	AuditPinnedBytes    int64            `json:"audit_pinned_bytes"`
	PackBlockedBytes    int64            `json:"pack_blocked_bytes"`
}

type PlacementRequest added in v0.12.0 

type PlacementRequest struct {
	TargetNodeID           int64  `json:"target_node_id"`
	SourceStoreID          string `json:"source_store_id"`
	DestinationStoreID     string `json:"destination_store_id"`
	RetireSource           bool   `json:"retire_source"`
	Evacuate               bool   `json:"evacuate,omitzero"`
	AllowAuditedRemoteOnly bool   `json:"allow_audited_remote_only"`
}

type ProvenanceFact added in v0.11.0 

type ProvenanceFact struct {
	Identity          string
	NodeID            int64
	IngestID          string
	IngestStartedAt   string
	SourceKind        string
	SourceDescription string
	OriginalPath      string
	OriginalMTime     *string
	Supersedes        *string
	Active            bool
}

ProvenanceFact is one immutable statement about where a document entered Docbank. A newer fact may supersede an older fact without rewriting it.

type RepackCandidate added in v0.10.0 

type RepackCandidate struct {
	Hash     string
	Usage    packstore.PackUsage
	Eligible bool
}

RepackCandidate binds one sparse pack to the lowest canonical live blob hash that provides its stable maintenance key.

type RepackScanPage added in v0.10.0 

type RepackScanPage struct {
	Items []RepackCandidate
	More  bool
}

type SearchHit 

type SearchHit struct {
	Node  Node
	Path  string
	Match string
}

SearchHit is a search result with its display path.

type SearchOptions added in v0.11.0 

type SearchOptions struct {
	TagID          string
	MIMEType       string
	UnderNodeID    int64
	ModifiedSince  string
	ModifiedBefore string
}

SearchOptions narrows ranked search without changing its name-before-content ordering. TagID identifies one required assignment; MIMEType selects the current file version's parameter-free base media type; UnderNodeID selects descendants of one live directory. ModifiedSince is inclusive and ModifiedBefore is exclusive; both accept absolute RFC3339 timestamps.

type StorageOperation added in v0.12.0 

type StorageOperation struct {
	ID               string
	Kind             string
	SourceStoreID    string
	RequestVersion   int64
	RequestDigest    string
	RequestJSON      string
	PlanJSON         string
	State            StorageOperationState
	Cursor           string
	TotalObjects     int64
	CompletedObjects int64
	CopiedObjects    int64
	CopiedBytes      int64
	CancelRequested  bool
	Error            string
	ReceiptJSON      string
	CreatedAt        time.Time
	UpdatedAt        time.Time
	FinishedAt       *time.Time
	RetentionUntil   *time.Time
}

type StorageOperationCleanup added in v0.12.0 

type StorageOperationCleanup struct {
	StoreID string
	Ref     packstore.ObjectRef
}

type StorageOperationCreate added in v0.12.0 

type StorageOperationCreate struct {
	Kind            string
	SourceStoreID   string
	StoreReferences []StorageOperationStoreReference
	RequestDigest   string
	RequestJSON     string
	PlanJSON        string
	TotalObjects    int64
}

type StorageOperationState added in v0.12.0 

type StorageOperationState string
const (
	StorageOperationQueued    StorageOperationState = "queued"
	StorageOperationRunning   StorageOperationState = "running"
	StorageOperationCompleted StorageOperationState = "completed"
	StorageOperationFailed    StorageOperationState = "failed"
	StorageOperationCancelled StorageOperationState = "cancelled"
)

type StorageOperationStoreReference added in v0.12.0 

type StorageOperationStoreReference struct {
	StoreID string
	Role    string
}

type StorageRecoveryPlan added in v0.12.0 

type StorageRecoveryPlan struct {
	Version     int                      `json:"version"`
	Kind        string                   `json:"kind"`
	Digest      string                   `json:"digest"`
	Hash        string                   `json:"hash"`
	Size        int64                    `json:"size"`
	Sources     []packstore.ReadLocation `json:"sources"`
	Destination string                   `json:"destination"`
	Prior       *packstore.ReadLocation  `json:"prior,omitempty"`
}

StorageRecoveryPlan binds one explicit repair or fenced-store salvage to immutable content identity and the exact physical candidates reviewed.

type Store 

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

Store is the single access path to the docbank database.

func Open 

func Open(path string, drivers ...docsqlite.Driver) (*Store, error)

Open opens (creating if needed) the database at path, applies the schema, and guarantees the root directory node exists. When driver is omitted, CGO builds use mattn/go-sqlite3 and no-CGO builds use modernc.org/sqlite.

func (*Store) AddRestoredBlobLocation added in v0.12.0 

func (s *Store) AddRestoredBlobLocation(
	ctx context.Context,
	hash string,
	destination packstore.ReadLocation,
) error

AddRestoredBlobLocation grants authority to bytes independently verified during an explicit restore remap. The source primary remains authoritative until the complete mapped copy set has committed.

func (*Store) AdvanceStorageOperation added in v0.12.0 

func (s *Store) AdvanceStorageOperation(
	ctx context.Context, id, cursor string,
	completedObjects, copiedObjects, copiedBytes int64,
	progressJSON ...string,
) error

func (*Store) AllBlobHashes 

func (s *Store) AllBlobHashes(ctx context.Context) ([]string, error)

AllBlobHashes lists every recorded blob identity without reading ancillary metadata. Integrity verification uses this after separately validating the metadata stream, so one malformed scalar does not suppress the useful report.

func (*Store) AllBlobs 

func (s *Store) AllBlobs(ctx context.Context) ([]BlobInfo, error)

AllBlobs lists every recorded blob, hash-ordered.

func (*Store) AssignTag 

func (s *Store) AssignTag(
	ctx context.Context, tagID string, nodeID, ifRev int64,
) (TagAssignmentChange, error)

AssignTag attaches a tag to a node under an optimistic revision check. Repeating an existing assignment is an idempotent no-op only when ifRev still matches the current node revision.

func (*Store) AssignTagPath 

func (s *Store) AssignTagPath(
	ctx context.Context, tagID, path string,
) (TagAssignmentChange, error)

AssignTagPath resolves a live path and assigns a tag in the same transaction.

func (*Store) AuditHistory 

func (s *Store) AuditHistory(
	ctx context.Context, nodeID int64, limit int, cursor string,
) (AuditEventPage, error)

AuditHistory returns one bounded page for a stable node ID, including trash.

func (*Store) AuditHistoryPath 

func (s *Store) AuditHistoryPath(
	ctx context.Context, path string, limit int, cursor string,
) (AuditEventPage, error)

AuditHistoryPath resolves one live path in the same snapshot as its history.

func (*Store) AuditScopeHistory added in v0.10.1 

func (s *Store) AuditScopeHistory(
	ctx context.Context, scopeID string, limit int, cursor string,
) (AuditScopeEventPage, error)

AuditScopeHistory returns one bounded page across a stable audit scope.

func (*Store) AuditStatus 

func (s *Store) AuditStatus(ctx context.Context, nodeID *int64) (AuditStatus, error)

AuditStatus reports current authority and optionally the sticky membership of one stable node from one consistent database snapshot.

func (*Store) AuditStatusPath 

func (s *Store) AuditStatusPath(ctx context.Context, path string) (AuditStatus, error)

AuditStatusPath resolves one live path and its sticky membership in the same read snapshot as the vault-wide authority evidence.

func (*Store) BatchMove added in v0.10.1 

func (s *Store) BatchMove(ctx context.Context, requests []BatchMoveRequest) ([]BatchMoveResult, error)

BatchMove applies the requested reorganization as one metadata transaction. Sources resolve against one pre-state. Exact destination coordinates resolve against the planned final tree, which is checked before any row changes.

func (*Store) BeginBlobStoreEvacuation added in v0.12.0 

func (s *Store) BeginBlobStoreEvacuation(ctx context.Context, selector string) error

BeginBlobStoreEvacuation makes one secondary read-only for new placement destinations while keeping its current locations readable during copying.

func (*Store) BeginEmbeddedIngest added in v0.11.0 

func (s *Store) BeginEmbeddedIngest(
	ctx context.Context, sourceKind, sourceDesc string,
) (IngestRun, error)

BeginEmbeddedIngest prepares generic provenance without interpreting any source kind as daemon-owned operational state.

func (*Store) BeginIngest 

func (s *Store) BeginIngest(ctx context.Context, sourceKind, sourceDesc string) (IngestRun, error)

BeginIngest prepares an authority-free ingest run. Its metadata is inserted atomically with the first file that actually imports, so audited vaults never contain a run whose provenance was committed in a separate transaction.

func (*Store) BeginMetadataSnapshot 

func (s *Store) BeginMetadataSnapshot(ctx context.Context) (*MetadataSnapshot, error)

BeginMetadataSnapshot establishes a pinned read transaction for logical backup capture. The initial read is required: BeginTx alone is lazy in SQLite and would not pin a snapshot before Kit releases the mutation gate.

func (*Store) BeginStorageRecoveryPublication added in v0.12.0 

func (s *Store) BeginStorageRecoveryPublication(
	ctx context.Context, operationID string, plan StorageRecoveryPlan,
) error

BeginStorageRecoveryPublication rejects a stale preview and makes the operation non-cancellable before physical replacement. The runner holds the destination location lock across this transition and catalog publication.

func (*Store) BeginWalk added in v0.10.0 

func (s *Store) BeginWalk(
	ctx context.Context, rootPath string, pageSize int, includeTrashed bool,
) (_ *Walker, retErr error)

BeginWalk pins a snapshot and seeds an incremental ordered frontier rooted at rootPath. Setup work depends on root-path depth, never subtree cardinality.

func (*Store) BlobHashesPage added in v0.10.0 

func (s *Store) BlobHashesPage(
	ctx context.Context, after string, limit int,
) ([]string, bool, error)

BlobHashesPage is the scalar-tolerant verification inventory. It does not scan ancillary blob metadata, so a malformed size remains reportable by ValidateMetadata without suppressing content verification.

func (*Store) BlobHashesPageFrom added in v0.10.0 

func (s *Store) BlobHashesPageFrom(
	ctx context.Context, after *string, limit int,
) ([]string, bool, error)

BlobHashesPageFrom distinguishes the beginning of an ordering from an arbitrary stored key, including the empty string.

func (*Store) BlobInfo added in v0.10.0 

func (s *Store) BlobInfo(ctx context.Context, hash string) (BlobInfo, error)

BlobInfo returns logical catalog membership independently of whether a loose or packed representation currently has physical read authority.

func (*Store) BlobStoreBySelector added in v0.12.0 

func (s *Store) BlobStoreBySelector(ctx context.Context, selector string) (BlobStore, error)

BlobStoreBySelector resolves canonical UUIDv4 selectors exclusively as IDs; all other selectors are names.

func (*Store) BlobStoreInventory added in v0.12.0 

func (s *Store) BlobStoreInventory(
	ctx context.Context,
) (map[string]BlobStoreStats, error)

BlobStoreInventory returns per-store authority without inspecting deployment namespaces or treating orphan files as catalog objects.

func (*Store) BlobStoreUnreadableObjects added in v0.12.0 

func (s *Store) BlobStoreUnreadableObjects(
	ctx context.Context, online map[string]bool,
) (map[string]int64, error)

BlobStoreUnreadableObjects counts each retained object against every store that holds it when none of its catalog locations are currently online. Runtime observations stay in Go and never rewrite durable authority.

func (*Store) BlobStores added in v0.12.0 

func (s *Store) BlobStores(ctx context.Context) ([]BlobStore, error)

BlobStores lists physical-store authority with the fixed primary first.

func (*Store) BlobsPage added in v0.10.0 

func (s *Store) BlobsPage(ctx context.Context, after string, limit int) ([]BlobInfo, bool, error)

BlobsPage returns one bounded hash-keyset page of recorded blob identities.

func (*Store) CheckContentReplacementTarget 

func (s *Store) CheckContentReplacementTarget(ctx context.Context, nodeID, ifRev int64) error

CheckContentReplacementTarget performs the cheap target and revision checks before a caller streams bytes. ReplaceContent repeats them transactionally, because this preflight is an optimization rather than mutation authority.

func (*Store) Checkpoint 

func (s *Store) Checkpoint(ctx context.Context) error

Checkpoint truncates the WAL after all application writes have completed. Portable restore uses it before closing a freshly imported database so the main file is self-contained and no sidecar is required for publication.

func (*Store) Children 

func (s *Store) Children(ctx context.Context, dirID int64) ([]Node, error)

Children lists the live children of a directory, dirs first, name-sorted.

func (*Store) ChildrenPage 

func (s *Store) ChildrenPage(
	ctx context.Context, dirID int64, limit, offset int,
) ([]Node, int, error)

ChildrenPage lists one bounded page of a directory's live children, dirs first and name-sorted, and returns the complete child count. Target kind, total, and page come from one statement so callers never observe a mixture across concurrent tree mutations.

func (*Store) ClaimStorageOperation added in v0.12.0 

func (s *Store) ClaimStorageOperation(
	ctx context.Context, id string,
) (StorageOperation, error)

func (*Store) Close 

func (s *Store) Close() error

Close closes the underlying database.

func (*Store) CommitPlacement added in v0.12.0 

func (s *Store) CommitPlacement(
	ctx context.Context,
	operationID string,
	request PlacementRequest,
	planned PlacementHash,
	destination packstore.ReadLocation,
) (PlacementCommit, error)

CommitPlacement grants a fully verified destination receipt and, when the current reference closure still permits it, revokes one loose source in the same short catalog transaction. Network I/O belongs before this boundary.

func (*Store) CommitStorageRecovery added in v0.12.0 

func (s *Store) CommitStorageRecovery(
	ctx context.Context, operationID string,
	plan StorageRecoveryPlan, receipt packstore.ReadLocation,
	operationReceiptJSON string, retentionUntil time.Time,
) error

CommitStorageRecovery grants the fully verified replacement generation.

func (*Store) CompleteStorageOperationCleanup added in v0.12.0 

func (s *Store) CompleteStorageOperationCleanup(
	ctx context.Context, operationID string, item StorageOperationCleanup,
) error

func (*Store) ConfirmContentWithReceipt added in v0.10.0 

func (s *Store) ConfirmContentWithReceipt(
	ctx context.Context, nodeID, ifRev int64, blobHash string, size int64, mimeType string,
	physical ...BlobPhysical,
) (ContentWriteReceipt, error)

ConfirmContentWithReceipt confirms that a file still has the expected immutable head while reconciling a newly published physical receipt. It is the transactional completion path for an otherwise idempotent write.

func (*Store) ConfirmIngestedContentWithReceipt added in v0.11.0 

func (s *Store) ConfirmIngestedContentWithReceipt(
	ctx context.Context, nodeID, ifRev int64, blobHash string, size int64, mimeType,
	sourceKind, sourceDescription, sourceReference, sourceModifiedAt string,
	physical ...BlobPhysical,
) (ContentWriteReceipt, error)

ConfirmIngestedContentWithReceipt is the idempotent completion path for an embedded immutable create with provenance. It succeeds only when the existing node has the same content authority and an active matching source fact, so a retry cannot silently claim evidence that was never recorded.

func (*Store) ContentReferencesByHash 

func (s *Store) ContentReferencesByHash(
	ctx context.Context, hash string, limit, offset int,
) ([]ContentReference, int, error)

ContentReferencesByHash returns one bounded, deterministic page of logical references to canonical SHA-256 content. A physical blob with no retained content version is not a match. Live current references sort first, followed by live history and then trashed references.

func (*Store) ContentVersionByID 

func (s *Store) ContentVersionByID(ctx context.Context, id string) (ContentVersion, error)

ContentVersionByID returns one version by its globally stable identity.

func (*Store) ContentVersionViewByID added in v0.12.0 

func (s *Store) ContentVersionViewByID(
	ctx context.Context, nodeID int64, versionID string,
) (ContentVersionView, error)

ContentVersionViewByID returns one node-owned version and its node authority from a single read transaction.

func (*Store) ContentVersions 

func (s *Store) ContentVersions(
	ctx context.Context, nodeID int64, limit, offset int,
) ([]ContentVersion, int, error)

ContentVersions lists one bounded page newest-first and returns the total number of versions recorded for the node.

func (*Store) CreateFile 

func (s *Store) CreateFile(
	ctx context.Context, parentID int64, name, blobHash string, size int64, mimeType string,
	physical ...BlobPhysical,
) (Node, error)

CreateFile creates a file node pointing at an already-durable blob.

func (*Store) CreateFileWithReceipt added in v0.10.0 

func (s *Store) CreateFileWithReceipt(
	ctx context.Context, parentID int64, name, blobHash string, size int64, mimeType string,
	physical ...BlobPhysical,
) (ContentWriteReceipt, error)

CreateFileWithReceipt creates a file node and returns its complete committed content authority.

func (*Store) CreateStorageOperation added in v0.12.0 

func (s *Store) CreateStorageOperation(
	ctx context.Context, input StorageOperationCreate,
) (StorageOperation, error)

func (*Store) CreateTag 

func (s *Store) CreateTag(ctx context.Context, name string) (Tag, error)

CreateTag defines a tag with a fresh stable identity.

func (*Store) DeadPackUsagePage added in v0.10.0 

func (s *Store) DeadPackUsagePage(
	ctx context.Context, limit int,
) ([]packstore.PackUsage, bool, error)

func (*Store) DeferStorageOperation added in v0.12.0 

func (s *Store) DeferStorageOperation(ctx context.Context, id string, failure error) error

DeferStorageOperation records a retryable worker failure and returns the operation to the durable queue without presenting it as actively running.

func (*Store) DeferTextExtraction 

func (s *Store) DeferTextExtraction(
	ctx context.Context, blobHash string, notBefore time.Time,
) error

DeferTextExtraction leaves a retryable item queued but moves it behind work that is ready now. The worker chooses the bounded delay in Go.

func (*Store) DeleteBlobRows 

func (s *Store) DeleteBlobRows(ctx context.Context, hashes []string) error

DeleteBlobRows removes logical membership and derived metadata for reclaimed blobs. Callers must hold the exclusive vault lock (see UnreachableBlobs) and retire every loose location first. Packed entries remain as dead physical accounting until repack retires their immutable container.

func (*Store) DeleteTag 

func (s *Store) DeleteTag(ctx context.Context, id string, ifRev int64) (Tag, error)

DeleteTag removes one definition and all of its assignments, advancing each formerly assigned node's metadata revision exactly once.

func (*Store) DeleteUnreferencedPackMappings added in v0.10.0 

func (s *Store) DeleteUnreferencedPackMappings(ctx context.Context, hashes []string) (int64, error)

DeleteUnreferencedPackMappings conditionally removes the named stale mappings. A blob authority restored after selection protects its mapping.

func (*Store) DetachBlobStore added in v0.12.0 

func (s *Store) DetachBlobStore(ctx context.Context, selector string) error

DetachBlobStore removes an empty secondary from ordinary backend admission while retaining its stable catalog identity for explicit unregister.

func (*Store) DirectoryChildrenPage added in v0.11.0 

func (s *Store) DirectoryChildrenPage(
	ctx context.Context, dirID int64, limit, offset int,
) (DirectoryPageView, error)

DirectoryChildrenPage returns a live directory's current canonical path and one ordered child page from a single read transaction.

func (*Store) EnableInitialAudit 

func (s *Store) EnableInitialAudit(
	ctx context.Context, plan *AuditEnrollmentPlan,
) (AuditStatus, error)

EnableInitialAudit commits a previously reviewed scope only when its baseline and allocation authority still exactly match current metadata.

func (*Store) EnsureBlobTx 

func (s *Store) EnsureBlobTx(tx *sql.Tx, hash string, size int64, physical ...BlobPhysical) error

EnsureBlobTx records a blob row if missing. The blob file must already be durable on disk before the enclosing transaction commits. If a blob row already exists under hash, its recorded size must match size and it must still have catalog-authorized loose or packed bytes. Missing physical authority requires explicit verified repair; an ordinary write receipt is not sufficient to adopt potentially unverified deduplicated bytes.

func (*Store) EnsureDir 

func (s *Store) EnsureDir(ctx context.Context, parentID int64, name string) (Node, error)

EnsureDir returns the live directory named name under parentID, creating it if missing and converging on a concurrent creation. ID-based on purpose: callers that resolved a destination once (ingest) must not re-derive it from a path, which a concurrent move or trash can redirect.

func (*Store) ExportMetadata 

func (s *Store) ExportMetadata(ctx context.Context, w io.Writer) error

ExportMetadata writes a deterministic JSONL description of Docbank's logical state. Rebuildable FTS data and physical pack authority are omitted.

func (*Store) FinalizeBlobStoreEvacuation added in v0.12.0 

func (s *Store) FinalizeBlobStoreEvacuation(
	ctx context.Context, operationID, sourceID, destinationID string,
) (BlobStoreEvacuationFinalization, error)

FinalizeBlobStoreEvacuation atomically proves complete destination coverage and revokes every source location. A source remains draining while durable physical cleanup is pending, then a repeated call detaches it.

func (*Store) FinishStorageOperation added in v0.12.0 

func (s *Store) FinishStorageOperation(
	ctx context.Context, id string, state StorageOperationState,
	receiptJSON, failure string, retentionUntil time.Time,
) error

func (*Store) HasBlob 

func (s *Store) HasBlob(ctx context.Context, hash string) (bool, error)

HasBlob reports whether the metadata catalog grants authority to hash.

func (*Store) HasPrimaryLooseAuthority added in v0.12.0 

func (s *Store) HasPrimaryLooseAuthority(ctx context.Context, hash string) (bool, error)

HasPrimaryLooseAuthority reports whether the built-in primary catalog still authorizes a canonical loose representation for hash. Physical scans use this narrower question so redundant files left by packing, placement, or a remote-only restore can be reclaimed without deleting logical membership.

func (*Store) ImportMetadata 

func (s *Store) ImportMetadata(ctx context.Context, r io.Reader) error

ImportMetadata replaces the pristine root in a newly created store with a logical JSONL snapshot. It refuses a store containing user or pack state.

func (*Store) Info added in v0.10.1 

func (s *Store) Info(ctx context.Context) (VaultInfo, error)

Info returns a point-in-time logical inventory without changing the vault.

func (*Store) IngestFile 

func (s *Store) IngestFile(ctx context.Context, run IngestRun, parentID int64, name, blobHash string, size int64, mimeType, originalPath, originalMtime string, physical ...BlobPhysical) (Node, bool, error)

IngestFile imports one already-durable blob as a node under parentID, applying the idempotency rule and recording provenance. Returns added=false when the content is already present under a candidate name.

func (*Store) IngestFileExact 

func (s *Store) IngestFileExact(ctx context.Context, run IngestRun, parentID int64, name, blobHash string, size int64, mimeType, originalPath, originalMtime string, physical ...BlobPhysical) (Node, error)

IngestFileExact imports one already-durable blob under exactly name. Unlike bulk migration it never suffixes or adopts an existing same-content node; a watched source needs its configured source identity to remain one-to-one.

func (*Store) IngestFileExactWithReceipt added in v0.11.0 

func (s *Store) IngestFileExactWithReceipt(
	ctx context.Context, run IngestRun, parentID int64, name, blobHash string,
	size int64, mimeType, originalPath, originalMtime string, physical ...BlobPhysical,
) (ContentWriteReceipt, error)

IngestFileExactWithReceipt is the receipt-bearing form used by embedded immutable creation. File, version, provenance, ingest, and physical catalog authority commit in one metadata transaction.

func (*Store) LiveTaggedNodes added in v0.12.0 

func (s *Store) LiveTaggedNodes(
	ctx context.Context, tagID string, limit, offset int,
) ([]TaggedNode, int, int, error)

LiveTaggedNodes lists one ID-sorted page of live nodes carrying tagID. The omitted count covers trashed assignments in the same read snapshot.

func (*Store) LooseBacklog added in v0.10.0 

func (s *Store) LooseBacklog(ctx context.Context) (LooseBacklog, error)

LooseBacklog returns indexed packing work without walking blob directories.

func (*Store) Mkdir 

func (s *Store) Mkdir(ctx context.Context, parentID int64, name string) (Node, error)

Mkdir creates a directory under parentID.

func (*Store) MkdirAll 

func (s *Store) MkdirAll(ctx context.Context, path string) (Node, error)

MkdirAll creates every missing directory along path and returns the leaf.

func (*Store) MkdirPath added in v0.11.0 

func (s *Store) MkdirPath(ctx context.Context, path string) (Node, string, error)

MkdirPath resolves the parent and creates one directory in the same transaction. This is the path-coordinate form for callers whose intent is tied to an exact virtual location rather than a previously resolved parent identity.

func (*Store) MkdirWithPath added in v0.11.0 

func (s *Store) MkdirWithPath(
	ctx context.Context, parentID int64, name string,
) (Node, string, error)

MkdirWithPath creates a directory under a stable parent identity and returns the new node's canonical path from the same mutation transaction.

func (*Store) Move 

func (s *Store) Move(
	ctx context.Context, id, newParentID int64, newName string, ifRev int64,
) (Node, string, error)

Move renames and/or reparents a live node in one transaction. Unless ifRev is UnconditionalRev, the mutation fails with ErrStaleRevision unless ifRev matches the node's current revision. The returned canonical path is captured in the mutation transaction with the returned node.

func (*Store) MovePath 

func (s *Store) MovePath(ctx context.Context, srcPath, destPath string) (Node, string, error)

MovePath resolves srcPath and destPath and moves inside one transaction, so a concurrent operation cannot relocate either path between resolution and mutation. A destPath naming an existing live directory means "move into, keep name"; otherwise its parent must exist and its basename becomes the new name. The returned canonical path is captured in the mutation transaction with the returned node.

func (*Store) MovePathRevision added in v0.10.0 

func (s *Store) MovePathRevision(
	ctx context.Context, srcPath, destPath string, ifRev int64,
) (Node, string, error)

MovePathRevision is MovePath with an exact optional revision precondition.

func (*Store) MoveToPath added in v0.10.0 

func (s *Store) MoveToPath(
	ctx context.Context, id, ifRev int64, destPath string,
) (Node, string, error)

MoveToPath moves the stable live node id to destPath while resolving the destination and enforcing ifRev in one transaction. Unlike MovePath, source identity is unaffected by concurrent ancestor moves.

func (*Store) NodeByID 

func (s *Store) NodeByID(ctx context.Context, id int64) (Node, error)

NodeByID returns the node with the given id, live or trashed.

func (*Store) NodeByPath 

func (s *Store) NodeByPath(ctx context.Context, path string) (Node, error)

NodeByPath walks live nodes from the root along the given /-separated path.

func (*Store) NodeProvenance added in v0.11.0 

func (s *Store) NodeProvenance(
	ctx context.Context, nodeID int64, limit, offset int,
) (NodeProvenancePage, error)

NodeProvenance returns immutable origin facts for one file node. The node, live path, count, and page come from one read snapshot so the response cannot combine provenance with a later move or trash operation.

func (*Store) NodeTags 

func (s *Store) NodeTags(ctx context.Context, nodeID int64, limit, offset int) ([]Tag, int, error)

NodeTags lists one name-sorted page of tags assigned to a node.

func (*Store) NodeViewByID added in v0.11.0 

func (s *Store) NodeViewByID(ctx context.Context, id int64) (NodeView, error)

NodeViewByID returns a node and its live path from one read transaction.

func (*Store) NodeViewByPath added in v0.11.0 

func (s *Store) NodeViewByPath(ctx context.Context, path string) (NodeView, error)

NodeViewByPath resolves a live path and returns its node and canonical path from one read transaction.

func (*Store) PackedBlobStoredByte added in v0.10.0 

func (s *Store) PackedBlobStoredByte(ctx context.Context, hash string) (int64, bool, error)

PackedBlobStoredByte reports one blob's immutable-pack payload length.

func (*Store) PackedBlobStoredBytes 

func (s *Store) PackedBlobStoredBytes(ctx context.Context) (map[string]int64, error)

PackedBlobStoredBytes returns the physical stored length of every cataloged packed blob. GC uses it to distinguish bytes unlinked immediately from dead immutable-pack space that requires a later repack.

func (*Store) Path 

func (s *Store) Path(ctx context.Context, id int64) (string, error)

Path returns the display path of a node ("/" for the root).

func (*Store) PendingTextExtractions 

func (s *Store) PendingTextExtractions(
	ctx context.Context, limit int,
) ([]ExtractionCandidate, error)

PendingTextExtractions returns a bounded hash-ordered batch from the derived work queue. Logical writes and one startup seed of selected versions fill the queue, so steady-state polling never scans the version catalog.

func (*Store) PhysicalContent added in v0.10.0 

func (s *Store) PhysicalContent(ctx context.Context, hash string) (PhysicalContent, error)

PhysicalContent returns the indexed representation with current catalog authority for hash.

func (*Store) PlanPlacement added in v0.12.0 

func (s *Store) PlanPlacement(
	ctx context.Context, request PlacementRequest,
) (PlacementPlan, error)

func (*Store) PlanStorageRecovery added in v0.12.0 

func (s *Store) PlanStorageRecovery(
	ctx context.Context, kind, hash, storeSelector string,
) (StorageRecoveryPlan, error)

func (*Store) PrepareSecondaryBlobStore added in v0.12.0 

func (s *Store) PrepareSecondaryBlobStore(name, kind, binding string) (BlobStore, error)

PrepareSecondaryBlobStore allocates the stable identity and ownership epoch that must be published to the physical namespace before RegisterBlobStore grants catalog authority.

func (*Store) PrepareStorageOperationCleanup added in v0.12.0 

func (s *Store) PrepareStorageOperationCleanup(
	ctx context.Context, operationID string, item StorageOperationCleanup,
) (bool, error)

PrepareStorageOperationCleanup determines whether a retired physical object is still safe to remove. If the exact object has become authoritative again, it atomically consumes the stale cleanup item and returns false.

func (*Store) PreviewInitialAudit 

func (s *Store) PreviewInitialAudit(
	ctx context.Context, targetNodeID int64, origin string, agentLabel *string,
) (*AuditEnrollmentPlan, error)

PreviewInitialAudit derives the exact next permanent scope without writing it. The first scope creates vault authority; later scopes must be disjoint.

func (*Store) PreviewInitialAuditPath 

func (s *Store) PreviewInitialAuditPath(
	ctx context.Context, path, origin string, agentLabel *string,
) (*AuditEnrollmentPlan, error)

PreviewInitialAuditPath resolves a live path and derives its exact enrollment boundary in the same database snapshot.

func (*Store) PrimaryBlobStore added in v0.12.0 

func (s *Store) PrimaryBlobStore(ctx context.Context) (BlobStore, error)

PrimaryBlobStore returns the fixed local filesystem store.

func (*Store) PrimaryBlobStoreID added in v0.12.0 

func (s *Store) PrimaryBlobStoreID() string

PrimaryBlobStoreID returns the stable catalog identity of the built-in filesystem store.

func (*Store) PruneContentVersions 

func (s *Store) PruneContentVersions(
	ctx context.Context, nodeID, ifRev int64, selector VersionPruneSelector, run bool,
) (VersionPruneResult, error)

PruneContentVersions previews or removes selected non-current history under an optimistic node revision. A run that changes history advances the node revision once. Revert-source dependencies remain retained unless AllPrior creates a new source-free checkpoint head in the same transaction.

func (*Store) PruneExpiredStorageOperations added in v0.12.0 

func (s *Store) PruneExpiredStorageOperations(
	ctx context.Context, now time.Time,
) (int64, error)

PruneExpiredStorageOperations removes terminal operation receipts after their retention boundary while preserving every operation that still owns pending physical cleanup.

func (*Store) RecordExtraction 

func (s *Store) RecordExtraction(ctx context.Context, result ExtractionResult) error

RecordExtraction atomically replaces one extractor's derived result and its searchable projection. It never changes document, version, or audit state.

func (*Store) RegisterBlobStore added in v0.12.0 

func (s *Store) RegisterBlobStore(ctx context.Context, candidate BlobStore) error

RegisterBlobStore records a namespace only after its ownership marker has been durably published and independently read back by the caller.

func (*Store) RenameTag 

func (s *Store) RenameTag(ctx context.Context, id string, ifRev int64, name string) (Tag, error)

RenameTag changes a tag's display name under an optimistic tag revision and advances every assigned node's metadata revision. Repeating the current name is an idempotent no-op only when ifRev still matches.

func (*Store) RepairBlobAuthority added in v0.10.0 

func (s *Store) RepairBlobAuthority(
	ctx context.Context, hash string, size int64, physical BlobPhysical,
) (int64, error)

RepairBlobAuthority atomically makes one already-verified loose receipt the physical authority for an existing blob. Logical membership, nodes, content versions, and immutable pack bytes are preserved; only the packed mapping is retired so maintenance can reclaim its dead bytes later.

func (*Store) ReplaceContent 

func (s *Store) ReplaceContent(
	ctx context.Context, nodeID, ifRev int64, blobHash string, size int64, mimeType string,
	physical ...BlobPhysical,
) (Node, ContentVersion, error)

ReplaceContent installs one already-durable blob as a file's new immutable head. Unless ifRev is UnconditionalRev, the node must still be at ifRev; version creation, pointer replacement, and the node revision bump commit as one transaction.

func (*Store) ReplaceContentWithReceipt added in v0.10.0 

func (s *Store) ReplaceContentWithReceipt(
	ctx context.Context, nodeID, ifRev int64, blobHash string, size int64, mimeType string,
	physical ...BlobPhysical,
) (ContentWriteReceipt, error)

ReplaceContentWithReceipt installs a new immutable head and returns its complete authority from the committing transaction.

func (*Store) RequestStorageOperationCancel added in v0.12.0 

func (s *Store) RequestStorageOperationCancel(ctx context.Context, id string) error

func (*Store) ResolveBlobLocations added in v0.12.0 

func (s *Store) ResolveBlobLocations(
	ctx context.Context,
	hash packstore.Hash,
) (packstore.Resolution, error)

ResolveBlobLocations returns the application-authorized read candidates for hash. Task 5 exposes only the built-in primary; later placement work adds secondaries and policy ordering without changing Kit's read path.

func (*Store) Restore 

func (s *Store) Restore(ctx context.Context, id, ifRev int64) (Node, string, error)

Restore returns a trash root to its original location (or the tree root if that location is gone), re-suffixing on conflict. Descendants trashed in earlier separate operations stay trashed. Unless ifRev is UnconditionalRev, the mutation fails with ErrStaleRevision unless ifRev matches the node's current revision. The returned canonical path is captured in the restore transaction with the returned node.

func (*Store) ResumableStorageOperations added in v0.12.0 

func (s *Store) ResumableStorageOperations(ctx context.Context) ([]StorageOperation, error)

func (*Store) RetireRestoredPrimary added in v0.12.0 

func (s *Store) RetireRestoredPrimary(
	ctx context.Context, hash string, allowAuditedRemoteOnly bool,
) (retired bool, err error)

RetireRestoredPrimary revokes temporary local catalog authority only after a verified secondary is authoritative. The physical file remains until the restored database is published and ordinary garbage collection removes it. Audited bytes remain primary-pinned unless the restore mapping explicitly acknowledges remote-only retention.

func (*Store) RevertContent 

func (s *Store) RevertContent(
	ctx context.Context, nodeID, ifRev int64, sourceVersionID string,
) (Node, ContentVersion, ContentVersion, error)

RevertContent creates a new immutable head with the exact content authority and media type of sourceVersionID. It records the source identity rather than rewinding the node or changing any historical row.

func (*Store) RootID 

func (s *Store) RootID() int64

RootID returns the id of the tree root.

func (*Store) SQLiteDriver 

func (s *Store) SQLiteDriver() docsqlite.Driver

SQLiteDriver returns the exact adapter used by this store. Backup snapshots and embedded lifecycle helpers reuse it for every auxiliary connection.

func (*Store) SearchPage 

func (s *Store) SearchPage(ctx context.Context, query string, limit int) ([]SearchHit, bool, error)

SearchPage returns live name matches in their established order, followed by content-only matches. Keeping the two ranks separate preserves the deterministic name-search contract: enabling extraction never reorders or hides a filename match that the same limit returned before.

func (*Store) SearchPageWithOptions added in v0.11.0 

func (s *Store) SearchPageWithOptions(
	ctx context.Context, query string, limit int, opts SearchOptions,
) ([]SearchHit, bool, error)

SearchPageWithOptions returns ranked live matches that satisfy every requested filter. Filters apply equally to name and content candidates.

func (*Store) SeedTextExtractionQueue 

func (s *Store) SeedTextExtractionQueue(
	ctx context.Context, extractor string, version int64,
) error

SeedTextExtractionQueue discovers supported selected content once at daemon startup. Discovery and projection writes share one storage transaction, so a concurrent deletion cannot invalidate a selected version between those steps. Later logical writes enqueue in Go while existing vaults converge here.

func (*Store) SparseRepackPage added in v0.10.0 

func (s *Store) SparseRepackPage(
	ctx context.Context,
	after string,
	limit int,
	now time.Time,
	minAge time.Duration,
	minDeadBytes int64,
) ([]RepackCandidate, bool, error)

SparseRepackPage returns eligible non-empty sparse packs ordered by their unique lowest live canonical blob hash.

func (*Store) SparseRepackScanPage added in v0.10.0 

func (s *Store) SparseRepackScanPage(
	ctx context.Context,
	afterHash string,
	afterPackID string,
	limit int,
	now time.Time,
	minAge time.Duration,
	minDeadBytes int64,
) (RepackScanPage, error)

SparseRepackScanPage examines at most limit persisted pack summaries. Packs that do not satisfy the caller's thresholds still consume the finite scan budget, so selection work is independent of total catalog cardinality.

func (*Store) StorageOperation added in v0.12.0 

func (s *Store) StorageOperation(ctx context.Context, id string) (StorageOperation, error)

func (*Store) StorageOperationCleanups added in v0.12.0 

func (s *Store) StorageOperationCleanups(
	ctx context.Context, operationID string,
) ([]StorageOperationCleanup, error)

func (*Store) StorageOperations added in v0.12.0 

func (s *Store) StorageOperations(
	ctx context.Context, limit int,
) ([]StorageOperation, error)

func (*Store) SyncWatchedContent 

func (s *Store) SyncWatchedContent(
	ctx context.Context, watchName, sourceRef, blobHash string, size int64, mimeType string,
	physical ...BlobPhysical,
) (Node, ContentVersion, bool, error)

SyncWatchedContent resolves a watched source's stable node and compares the incoming bytes with the last bytes accepted from that source. The source cursor is deliberately independent of the node's selected version: a manual edit or revert must survive daemon restart when the source did not change.

func (*Store) TagByID 

func (s *Store) TagByID(ctx context.Context, id string) (Tag, error)

TagByID returns one tag by stable identity.

func (*Store) TagByName 

func (s *Store) TagByName(ctx context.Context, name string) (Tag, error)

TagByName returns the tag whose normalized name exactly matches name.

func (*Store) TaggedNodes 

func (s *Store) TaggedNodes(ctx context.Context, tagID string, limit, offset int) ([]TaggedNode, int, error)

TaggedNodes lists one ID-sorted page of nodes carrying tagID.

func (*Store) Tags 

func (s *Store) Tags(ctx context.Context, limit, offset int) ([]Tag, int, error)

Tags lists one name-sorted page and the total number of definitions.

func (*Store) Trash 

func (s *Store) Trash(ctx context.Context, id, ifRev int64) (Node, string, error)

Trash soft-deletes a live node and its live subtree as a unit. All subtree rows share one trashed_at stamp; only the top node records its original location for restore. Unless ifRev is UnconditionalRev, the mutation fails with ErrStaleRevision unless ifRev matches the node's current revision. Returns the node as it stands after trashing, plus its pre-trash path — computed inside the same transaction, because trashing re-parents the node (making the path uncomputable afterwards) and a concurrent ancestor move could stale a path captured beforehand.

func (*Store) TrashEmpty 

func (s *Store) TrashEmpty(ctx context.Context, olderThan time.Duration, run bool) (TrashEmptyResult, error)

TrashEmpty reports trash roots older than the cutoff and, when run is true, hard-deletes them. A zero age selects every trash root, including any with a future timestamp caused by clock skew. Subtrees follow via ON DELETE CASCADE.

func (*Store) TrashEmptyBounded added in v0.10.0 

func (s *Store) TrashEmptyBounded(
	ctx context.Context, olderThan time.Duration, maxRoots int, run bool,
) (TrashEmptyResult, error)

TrashEmptyBounded reports or deletes at most maxRoots eligible trash roots. More reports whether another eligible root existed beyond this batch.

func (*Store) TrashPath 

func (s *Store) TrashPath(ctx context.Context, path string) (Node, string, error)

TrashPath resolves path and trashes the node inside one transaction, so a concurrent move cannot relocate the node or an ancestor between resolution and mutation. Returns the node that was trashed and its canonical pre-trash path (see Trash).

func (*Store) TrashPathRevision added in v0.10.0 

func (s *Store) TrashPathRevision(
	ctx context.Context, path string, ifRev int64,
) (Node, string, error)

TrashPathRevision is TrashPath with an exact optional revision precondition.

func (*Store) TrashedRoots 

func (s *Store) TrashedRoots(ctx context.Context) ([]Node, error)

TrashedRoots lists restorable trash roots, newest first.

func (*Store) TrashedRootsPage added in v0.12.0 

func (s *Store) TrashedRootsPage(
	ctx context.Context, limit, offset int,
) ([]Node, int, error)

TrashedRootsPage lists one bounded newest-first page of restorable trash roots and the complete root count from the same read snapshot.

func (*Store) UnassignTag 

func (s *Store) UnassignTag(
	ctx context.Context, tagID string, nodeID, ifRev int64,
) (TagAssignmentChange, error)

UnassignTag removes a tag from a node under an optimistic revision check. Repeating an absent assignment is an idempotent no-op only when ifRev still matches the current node revision.

func (*Store) UnassignTagPath 

func (s *Store) UnassignTagPath(
	ctx context.Context, tagID, path string,
) (TagAssignmentChange, error)

UnassignTagPath resolves a live path and removes a tag in the same transaction.

func (*Store) UnreachableBlobs 

func (s *Store) UnreachableBlobs(ctx context.Context) ([]BlobInfo, error)

UnreachableBlobs lists blobs referenced by no content version. Every current file head is itself a content version, as are retained prior versions. These are the gc candidates. Callers that go on to delete blob files must serialize against concurrent writers (the daemon's maintenance gate does this): with writers running, a concurrent ingest can dedup against a candidate's file between this query and the deletion, leaving a live node pointing at a removed blob.

func (*Store) UnreachableBlobsPageFrom added in v0.10.0 

func (s *Store) UnreachableBlobsPageFrom(
	ctx context.Context, after *string, limit int,
) (GCCandidateScanPage, error)

UnreachableBlobsPageFrom distinguishes the beginning of an ordering from an arbitrary stored key, including the empty string. It examines a bounded raw key window before filtering for unreachable work.

func (*Store) UnreferencedPackMappingsPage added in v0.10.0 

func (s *Store) UnreferencedPackMappingsPage(
	ctx context.Context, after *string, limit int,
) (StringScanPage, error)

UnreferencedPackMappingsPage returns one canonical-hash keyset page of pack mappings whose blob authority has been revoked.

func (*Store) UnregisterBlobStore added in v0.12.0 

func (s *Store) UnregisterBlobStore(ctx context.Context, selector string) error

UnregisterBlobStore removes an already detached, empty secondary identity.

func (*Store) ValidateMetadata 

func (s *Store) ValidateMetadata(ctx context.Context) (err error)

ValidateMetadata verifies the current relational metadata and, when audit authority exists, independently replays its canonical history against the current projection. It exercises the same deterministic stream boundary as backup without publishing that stream or mutating the vault.

func (*Store) VaultID 

func (s *Store) VaultID() string

VaultID returns the stable logical identity preserved by metadata export, backup, and restore. Moving or restoring a vault does not change it.

func (*Store) VerifyAudit 

func (s *Store) VerifyAudit(
	ctx context.Context, expected *AuditEvidence,
) (result AuditVerification, err error)

VerifyAudit independently replays canonical audit history against the current projections and returns externally recordable terminal evidence. Blob bytes are verified by the daemon through physical catalog authority after this metadata snapshot succeeds.

type StringScanPage added in v0.10.0 

type StringScanPage struct {
	Items     []string
	Examined  int
	HighWater string
	More      bool
}

StringScanPage reports bounded raw key progress for a filtered string inventory such as unreferenced packed mappings.

type Tag 

type Tag struct {
	ID              string
	Name            string
	Revision        int64
	AssignmentCount int
}

Tag is one stable organization label. Name is mutable; ID is permanent and never reused. AssignmentCount is the current number of tagged nodes.

type TagAssignmentChange 

type TagAssignmentChange struct {
	Node    Node
	Path    string
	Tag     Tag
	Changed bool
}

TagAssignmentChange is the transactionally consistent result of assigning or unassigning one tag. Path is populated only while Node is live.

type TaggedNode 

type TaggedNode struct {
	Node Node
	Path string
}

TaggedNode is one node carrying a tag plus its resolvable live path. Trashed nodes have an empty path.

type TrashEmptyResult 

type TrashEmptyResult struct {
	Candidates int64
	Deleted    int64
	More       bool
	Run        bool
}

TrashEmptyResult reports one trash-empty dry run or execution.

type VaultInfo added in v0.10.1 

type VaultInfo struct {
	VaultID             string
	LiveFiles           int64
	LiveDirectories     int64
	TrashedNodes        int64
	ContentVersions     int64
	LogicalVersionBytes int64
	TrackedBlobs        int64
	TrackedBlobBytes    int64
}

VaultInfo summarizes the logical authority held by a vault. Physical loose and packed storage is reported separately by the blob store.

type VersionPruneResult 

type VersionPruneResult struct {
	Node                         Node
	Candidates                   []ContentVersion
	DependencyRetained           []ContentVersion
	Checkpoint                   *ContentVersion
	Cutoff                       string
	LogicalBytes                 int64
	UniqueBlobs                  int
	SharedBlobs                  int
	ReleasableBlobs              int
	ReleasableBytes              int64
	LooseBlobsPendingGC          int
	LooseBytesPendingGC          int64
	PackedBlobsPendingRepack     int
	PackedBytesPendingRepack     int64
	MixedBlobsPendingMaintenance int
	DeletedVersions              int
	CheckpointRequired           bool
	Changed                      bool
	Run                          bool
}

VersionPruneResult is the complete dry-run inventory or execution receipt. LogicalBytes counts version references and may count a deduplicated blob more than once. ReleasableBytes counts unique blobs that become eligible for a later GC; pruning itself never reports physical bytes as reclaimed. Loose and packed maintenance counts may overlap when one blob has both location kinds across stores; MixedBlobsPendingMaintenance names that intersection.

type VersionPruneSelector 

type VersionPruneSelector struct {
	VersionIDs []string
	KeepNewest int
	OlderThan  time.Duration
	AllPrior   bool
}

VersionPruneSelector chooses historical content versions. Exactly one mode must be set. The current head is never removable; AllPrior may replace a current revert with a same-byte checkpoint so its complete source graph can be released.

type WalkEntry added in v0.10.0 

type WalkEntry struct {
	Path string
	Node Node
}

WalkEntry is one node and its canonical path in a pinned tree snapshot.

type WalkStats added in v0.10.0 

type WalkStats struct {
	SetupNodeReads       int64
	Pages                int64
	EntriesReturned      int64
	LastPageRowsExamined int64
	LastPageIndexedSeeks int64
}

WalkStats exposes deterministic traversal work without exposing the TEMP frontier implementation. RowsExamined counts frontier rows returned for the last page; each returned row performs at most two indexed sibling range seeks and, for a directory, one indexed first-child seek.

type Walker added in v0.10.0 

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

Walker pages through one tree snapshot held by a dedicated read transaction.

func (*Walker) Close added in v0.10.0 

func (w *Walker) Close() error

Close releases the snapshot transaction and its dedicated connection.

func (*Walker) Next added in v0.10.0 

func (w *Walker) Next(ctx context.Context) ([]WalkEntry, error)

Next returns the next bounded page in canonical path then node-ID order. The frontier contains only the next candidate from each explored sibling iterator. Expanding one returned node performs at most two next-sibling range seeks and, for a directory, one first-child seek. Live-only seeks use the partial live_sibling_names index; include-trash seeks use nodes_parent_name_id.

func (*Walker) Stats added in v0.10.0 

func (w *Walker) Stats() WalkStats

Stats returns a race-safe snapshot of deterministic walker work counters.

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.