docbank

README

docbank

Alpha software. Keep independent copies of irreplaceable material and verify backups before relying on them.

Your documents. Your agents. One system.

Docbank is a self-sovereign document system for the records you and your agents need to keep, find, change, and prove. It combines a familiar virtual tree with stable document IDs, immutable content versions, indexed retrieval, recoverable deletion, verified backup, and optional permanent audited history. The vault catalog stays under your control instead of inside a provider account.

The standalone CLI, web application, TUI, scripts, and agents all use the same authenticated daemon contract. Go applications can instead embed independently rooted vaults in-process through the public module at go.kenn.io/docbank.

Why Docbank?

A path is a useful place to find a file, but a poor long-term identity. Cloud drives also make account access and provider policy part of the authority for your archive. Docbank separates those concerns:

• a stable node ID continues to identify a document after moves and renames;
• every content version is immutable and named by a verifiable SHA-256 digest;
• revisions turn stale automation into explicit conflicts instead of silent overwrites;
• trash, permanent deletion, garbage collection, and pack reclamation are separate decisions;
• incremental backups are verified before restore results are published; and
• physical content can be placed in fenced filesystem or S3-compatible stores without making those stores the document catalog.

Docbank is an archive and system of record, not a sync-and-share service. It does not mirror a working folder across devices or create public share links.

What you can do

Need	Docbank capability
File and find records	Recursive import, verified upload, virtual folders, tags, ranked name and extracted-text search
Keep identity through change	Stable node IDs, immutable version UUIDs, verified replacement, reversion, and explicit version pruning
Work safely with agents	Authenticated HTTP and OpenAPI, bounded listings, structured errors, revision preconditions, and digest receipts
Recover from mistakes	Recoverable trash, revision-bound restore, explicit GC and repack, whole-vault verification
Prove recovery	Incremental snapshot repositories, complete content verification, topology-independent restore
Retain a permanent record	Preview-first audited scopes with sticky retention and independently replayed evidence
Manage physical capacity	Loose and packed storage, automatic bounded packing, and deliberate multi-store placement, repair, salvage, and evacuation

See the capability guide for the full product map and the visual tour for the current web and terminal interfaces.

Install

Linux or macOS:

curl -fsSL https://docbank.ai/install.sh | sh

Windows PowerShell:

irm https://docbank.ai/install.ps1 | iex

The installers select the native Linux, macOS, or Windows archive for amd64 or arm64 and refuse to install it unless its digest matches the release's SHA256SUMS. GitHub Releases also provides the archives for manual verification.

To build from source, install Go 1.27+, CGO, a C compiler, Node 24+, and npm:

git clone https://github.com/kenn-io/docbank.git
cd docbank
make install

The setup guide is the toolchain authority for every platform.

Start a vault

There is no initialization ceremony. The first data command creates the vault and starts its daemon:

docbank add ~/Documents --dest /archive
docbank tree /archive
docbank search "tax return"
docbank web

Retrieve a complete file only after Docbank verifies it, then inspect or change the same stable document without rewriting prior content:

docbank get /archive/Documents/receipt.pdf ./receipt.pdf
docbank versions list /archive/Documents/receipt.pdf
docbank put revised-receipt.pdf /archive/Documents/receipt.pdf
docbank mv /archive/Documents/receipt.pdf /archive/Documents/receipt-2026.pdf
docbank verify

Create and prove an incremental recovery point:

docbank backup init --repo ~/Backups/docbank
docbank backup create --repo ~/Backups/docbank --tag first-import
docbank backup verify --repo ~/Backups/docbank
docbank backup restore --repo ~/Backups/docbank --target ~/Restores/docbank-test

The ten-minute quickstart walks through versions, tags, search, recoverable trash, maintenance, and restore.

Deployment and trust boundaries

• Standalone: one daemon owns a vault; every CLI, browser, TUI, script, and external agent goes through its loopback-authenticated API.
• Embedded: one Go application owns each independently rooted vault in-process, with selectable CGO or pure-Go SQLite.
• Secondary storage: Docbank verifies content in configured filesystem and S3-compatible stores but does not encrypt it. Protect those namespaces with owner access controls and storage encryption appropriate to their operator.
• Backup: a stopped copy of the local database and primary blob directory is complete only when every retained blob still has primary authority. docbank backup create remains complete across remote-only placement and is the preferred portable recovery path.

Documentation

• Documentation homepage and visual tour
• Setup and quickstart
• Capabilities and vault lifecycle
• Web application and terminal browser
• Multi-store storage and backup & restore
• Docbank for agents and integration guide
• Embed in Go
• CLI reference and architecture overview

Docbank belongs to a family of personal data tools alongside msgvault, the communications archive. Msgvault preserves an immutable record of messages; Docbank manages working documents that people and agents still organize, retrieve, version, and use.

License

Copyright 2026 Kenn Software LLC.

Docbank is licensed under the Apache License, Version 2.0. See NOTICE for attribution information.

Documentation

Overview

Package docbank provides an in-process Docbank vault for Go applications. Standalone CLI commands remain daemon clients; embedded applications own the same exclusive vault lock, metadata schema, and mixed loose/packed storage directly through this lifecycle.

Index

• Constants
• Variables
• type BatchMoveItem
• type BatchMoveReceipt
• type ChildrenOptions
• type ChildrenPage
• type Config
• type Content
• type ContentIdentity
• type ContentVersion
• type CreateOptions
• type GCOptions
• type GCReport
• type LooseBacklog
• type LooseCompressionOptions
• type MaintenanceProgress
• type MutationReceipt
• type Node
• type PackOptions
• type PackReport
• type PhysicalContent
• type ProvenanceFact
• type ProvenanceOptions
• type ProvenancePage
• type ProvenanceSource
• type PutOptions
• type PutReceipt
• type RepackOptions
• type RepackReport
• type RepairReceipt
• type ResetOptions
• type RevisionOptions
• type StoreBinding
• type TrashEmptyOptions
• type TrashEmptyReport
• type Vault
  • func New(ctx context.Context, config Config) (_ *Vault, retErr error)
  • func ResetVault(ctx context.Context, config Config, opts ResetOptions) (fresh *Vault, retErr error)
  • func (v *Vault) BatchMove(ctx context.Context, moves []BatchMoveItem) ([]BatchMoveReceipt, error)
  • func (v *Vault) Children(ctx context.Context, directoryID int64, opts ChildrenOptions) (ChildrenPage, error)
  • func (v *Vault) Close() error
  • func (v *Vault) Create(ctx context.Context, virtualPath string, content io.Reader, opts CreateOptions) (PutReceipt, error)
  • func (v *Vault) EmptyTrash(ctx context.Context, opts TrashEmptyOptions) (TrashEmptyReport, error)
  • func (v *Vault) GarbageCollect(ctx context.Context, opts GCOptions) (GCReport, error)
  • func (v *Vault) ID() string
  • func (v *Vault) LooseBacklog(ctx context.Context) (LooseBacklog, error)
  • func (v *Vault) MovePath(ctx context.Context, from, to string, opts RevisionOptions) (MutationReceipt, error)
  • func (v *Vault) OpenContent(ctx context.Context, virtualPath string) (*Content, error)
  • func (v *Vault) OpenVersionContent(ctx context.Context, versionID string) (*VersionContent, error)
  • func (v *Vault) Pack(ctx context.Context, opts PackOptions) (PackReport, error)
  • func (v *Vault) Provenance(ctx context.Context, nodeID int64, opts ProvenanceOptions) (ProvenancePage, error)
  • func (v *Vault) Put(ctx context.Context, virtualPath string, content io.Reader, opts PutOptions) (PutReceipt, error)
  • func (v *Vault) Repack(ctx context.Context, opts RepackOptions) (RepackReport, error)
  • func (v *Vault) RepairContent(ctx context.Context, identity ContentIdentity, trusted io.Reader) (RepairReceipt, error)
  • func (v *Vault) Restore(ctx context.Context, nodeID int64, opts RevisionOptions) (MutationReceipt, error)
  • func (v *Vault) SQLiteDriver() string
  • func (v *Vault) Stat(ctx context.Context, virtualPath string) (Node, error)
  • func (v *Vault) TrashPath(ctx context.Context, path string, opts RevisionOptions) (MutationReceipt, error)
  • func (v *Vault) Verify(ctx context.Context, opts VerifyOptions) (VerifyReport, error)
  • func (v *Vault) Versions(ctx context.Context, nodeID int64, opts VersionsOptions) (VersionsPage, error)
  • func (v *Vault) Walk(ctx context.Context, rootPath string, opts WalkOptions) (*Walker, error)
• type VerifiedReadCloser
• type VerifyOptions
• type VerifyProblem
• type VerifyReport
• type VersionContent
• type VersionsOptions
• type VersionsPage
• type WalkEntry
• type WalkOptions
• type Walker
  • func (w *Walker) Close() error
  • func (w *Walker) Next(ctx context.Context) ([]WalkEntry, error)
• type WorkBudget

Constants

const (
	DefaultMaintenanceMaxObjects = internalmaintenance.DefaultMaxObjects
	MaxMaintenanceObjects        = internalmaintenance.MaxObjectsPerOperation
)

const (
	DefaultProvenanceLimit = 100
	MaxProvenanceLimit     = store.MaxProvenancePageSize
)

const (
	DefaultVersionsLimit = 100
	MaxVersionsLimit     = 1000
)

const (
	// DefaultChildrenLimit is the page size used when ChildrenOptions.Limit is zero.
	DefaultChildrenLimit = 500
	// MaxChildrenLimit is the largest child page one embedded call may materialize.
	MaxChildrenLimit = 5000
	// DefaultTrashEmptyMaxRoots bounds one EmptyTrash call when MaxRoots is zero.
	DefaultTrashEmptyMaxRoots = 100
)

const (
	// DefaultWalkPageSize is the finite page size used when WalkOptions.PageSize is zero.
	DefaultWalkPageSize = 500
	// MaxWalkPageSize is the largest page one Walker may materialize.
	MaxWalkPageSize = store.MaxWalkPageSize
	// MaxWalkDepth is the greatest absolute tree depth one Walker traverses.
	MaxWalkDepth = store.MaxWalkDepth
	// MaxWalkPathBytes is the largest canonical path one Walker materializes.
	MaxWalkPathBytes = store.MaxWalkPathBytes
)

const MaxBatchMoves = store.MaxBatchMoves

MaxBatchMoves is the largest all-or-nothing reorganization accepted by one embedded or daemon operation.

Variables

var (
	// ErrClosed means an operation targeted a closed embedded vault.
	ErrClosed = errors.New("docbank vault is closed")
	// ErrContentUnavailable means catalog-authorized content could not be
	// opened or its physical size disagreed with the metadata authority.
	ErrContentUnavailable = errors.New("docbank content is unavailable")
	// ErrDigestMismatch means the durable bytes did not match the caller's
	// optional expected SHA-256 identity.
	ErrDigestMismatch = errors.New("docbank content digest mismatch")
	// ErrSizeMismatch means the durable bytes did not match the caller's
	// optional expected byte count.
	ErrSizeMismatch = errors.New("docbank content size mismatch")
	// ErrContentConflict means immutable creation targeted an existing path
	// with different bytes, size, media type, provenance, or node kind.
	ErrContentConflict = errors.New("docbank immutable content conflict")

	ErrNotFound                 = store.ErrNotFound
	ErrExists                   = store.ErrExists
	ErrNotDirectory             = store.ErrNotDir
	ErrNotFile                  = store.ErrNotFile
	ErrStaleRevision            = store.ErrStaleRevision
	ErrCycle                    = store.ErrCycle
	ErrInvalidName              = store.ErrInvalidName
	ErrInvalidBatchMove         = store.ErrInvalidBatchMove
	ErrNotTrashed               = store.ErrNotTrashed
	ErrIsRoot                   = store.ErrIsRoot
	ErrAuditMutationUnsupported = store.ErrAuditMutationUnsupported
)

var ErrInvalidMaintenanceCursor = internalmaintenance.ErrInvalidCursor

Types

type BatchMoveItem

type BatchMoveItem struct {
	SourcePath      string `json:"source_path,omitzero"`
	NodeID          int64  `json:"node_id,omitzero"`
	IfRevision      int64  `json:"if_revision,omitzero"`
	DestinationPath string `json:"destination_path"`
}

BatchMoveItem identifies one live source either by SourcePath or by stable NodeID plus IfRevision. DestinationPath is an exact final coordinate whose parent is resolved in the batch's planned final tree.

type BatchMoveReceipt

type BatchMoveReceipt struct {
	Node     Node   `json:"node"`
	FromPath string `json:"from_path"`
	Path     string `json:"path"`
}

BatchMoveReceipt binds one request to its stable node and transactional pre/post coordinates.

type ChildrenOptions

type ChildrenOptions struct {
	Limit  int
	Offset int
}

ChildrenOptions selects one bounded page of a directory's live children. A zero Limit uses DefaultChildrenLimit. Offset must not be negative.

type ChildrenPage

type ChildrenPage struct {
	Items  []Node `json:"items"`
	Total  int    `json:"total"`
	Limit  int    `json:"limit"`
	Offset int    `json:"offset"`
}

ChildrenPage is one bounded dirs-first, name-sorted child listing.

type Config

type Config struct {
	Root             string
	SQLite           docsqlite.Driver
	LooseCompression LooseCompressionOptions
	StoreBindings    map[string]StoreBinding
}

Config selects one private vault root, its optional SQLite implementation, and physical loose-storage policy. Nil SQLite uses mattn/go-sqlite3 in CGO builds and modernc.org/sqlite when CGO is disabled.

type Content

type Content struct {
	Node   Node
	Reader VerifiedReadCloser
}

Content binds a verified current-byte stream to its stable node projection.

type ContentIdentity

type ContentIdentity struct {
	SHA256 string `json:"sha256"`
	Size   int64  `json:"size"`
}

ContentIdentity is the canonical identity of uncompressed document bytes.

type ContentVersion

type ContentVersion struct {
	ID                    string  `json:"id"`
	NodeID                int64   `json:"node_id"`
	BlobHash              string  `json:"blob_hash"`
	Size                  int64   `json:"size"`
	MediaType             string  `json:"media_type,omitzero"`
	RecordedAt            string  `json:"recorded_at"`
	NodeRevision          int64   `json:"node_revision"`
	IntroducedOperationID string  `json:"introduced_operation_id"`
	TransitionKind        string  `json:"transition_kind"`
	SourceVersionID       *string `json:"source_version_id,omitempty"`
}

ContentVersion is one immutable byte identity in a stable file's history.

type CreateOptions

type CreateOptions struct {
	MediaType string
	Expected  ContentIdentity
	// Provenance optionally records where this immutable document came from.
	// The source fact commits atomically with a newly created node and version.
	Provenance *ProvenanceSource
}

CreateOptions controls one immutable content creation. Expected is required; an existing path is idempotent only when bytes, size, and media type match.

type GCOptions

type GCOptions struct {
	Budget WorkBudget
	DryRun bool
}

type GCReport

type GCReport struct {
	MaintenanceProgress

	CandidateBlobs     int   `json:"candidate_blobs"`
	UntrackedFiles     int   `json:"untracked_files"`
	ReclaimableBytes   int64 `json:"reclaimable_bytes"`
	PendingPackedBlobs int   `json:"pending_packed_blobs"`
	PendingPackedBytes int64 `json:"pending_packed_bytes"`
	ReclaimedFiles     int   `json:"reclaimed_files"`
	RemovedBlobs       int   `json:"removed_blobs"`
	Removed            int   `json:"removed"`
	DryRun             bool  `json:"dry_run"`
}

GCReport summarizes one bounded catalog-authority reclamation pass.

type LooseBacklog

type LooseBacklog struct {
	EligibleObjects     int64 `json:"eligible_objects"`
	EligibleBytes       int64 `json:"eligible_bytes"`
	EligibleStoredBytes int64 `json:"eligible_stored_bytes"`
	RawObjects          int64 `json:"raw_objects"`
	CompressedObjects   int64 `json:"compressed_objects"`
}

LooseBacklog summarizes loose content eligible for explicit packing.

type LooseCompressionOptions

type LooseCompressionOptions struct {
	Enabled           bool
	MinBytes          int64
	MinSavingsPercent int
}

LooseCompressionOptions controls whether eligible new loose content may use zstd physical storage. The zero value preserves the legacy raw layout.

type MaintenanceProgress

type MaintenanceProgress struct {
	NextCursor string `json:"next_cursor,omitzero"`
	More       bool   `json:"more"`
}

type MutationReceipt

type MutationReceipt struct {
	Node Node   `json:"node"`
	Path string `json:"path"`
}

MutationReceipt binds the resulting node projection to the canonical path captured in the same metadata transaction.

type Node

type Node struct {
	ID               int64   `json:"id"`
	ParentID         *int64  `json:"parent_id,omitempty"`
	Name             string  `json:"name"`
	Kind             string  `json:"kind"`
	CurrentVersionID string  `json:"current_version_id,omitzero"`
	BlobHash         string  `json:"blob_hash,omitzero"`
	Size             int64   `json:"size"`
	MediaType        string  `json:"media_type,omitzero"`
	Revision         int64   `json:"revision"`
	CreatedAt        string  `json:"created_at"`
	ModifiedAt       string  `json:"modified_at"`
	TrashedAt        *string `json:"trashed_at,omitempty"`
}

Node is the current projection of one stable virtual-tree identity.

type PackOptions

type PackOptions struct {
	MaxBytes int64
}

PackOptions bounds one explicit embedded packing pass. MaxBytes is a soft committed raw-byte budget; zero is unlimited and negative values are rejected.

type PackReport

type PackReport struct {
	PacksSealed                int   `json:"packs_sealed"`
	BlobsPacked                int   `json:"blobs_packed"`
	BytesPacked                int64 `json:"bytes_packed"`
	PacksAdopted               int   `json:"packs_adopted"`
	PacksRemoved               int   `json:"packs_removed"`
	PacksQuarantined           int   `json:"packs_quarantined"`
	PacksUnreadable            int   `json:"packs_unreadable"`
	RecordsDropped             int   `json:"records_dropped"`
	MappingsPruned             int64 `json:"mappings_pruned"`
	BlobsMissing               int   `json:"blobs_missing"`
	BlobsCorrupt               int   `json:"blobs_corrupt"`
	BlobsDeferredOversized     int   `json:"blobs_deferred_oversized"`
	PacksDeferredOversized     int   `json:"packs_deferred_oversized"`
	LooseSwept                 int   `json:"loose_swept"`
	LooseOrphansRemoved        int   `json:"loose_orphans_removed"`
	LooseOrphanSweepSuppressed bool  `json:"loose_orphan_sweep_suppressed"`
	BudgetExhausted            bool  `json:"budget_exhausted"`
	More                       bool  `json:"more"`
}

PackReport summarizes one explicit packing and repair pass.

type PhysicalContent

type PhysicalContent struct {
	Kind         string `json:"kind"`
	Encoding     string `json:"encoding"`
	LogicalBytes int64  `json:"logical_bytes"`
	StoredBytes  int64  `json:"stored_bytes"`
	PackEligible bool   `json:"pack_eligible"`
}

PhysicalContent describes the representation with current catalog authority. Logical identity is always SHA-256 over decoded bytes.

type ProvenanceFact

type ProvenanceFact struct {
	Identity          string  `json:"identity"`
	NodeID            int64   `json:"node_id"`
	IngestID          string  `json:"ingest_id"`
	RecordedAt        string  `json:"recorded_at"`
	SourceKind        string  `json:"source_kind"`
	SourceDescription string  `json:"source_description"`
	SourceReference   string  `json:"source_reference"`
	SourceModifiedAt  *string `json:"source_modified_at,omitempty"`
	Supersedes        *string `json:"supersedes,omitempty"`
	Active            bool    `json:"active"`
}

ProvenanceFact is one immutable statement about where a document came from. Superseded facts remain visible; Active marks the current unsuperseded facts.

type ProvenanceOptions

type ProvenanceOptions struct {
	Limit  int
	Offset int
}

ProvenanceOptions selects one bounded newest-first provenance page.

type ProvenancePage

type ProvenancePage struct {
	Node   Node             `json:"node"`
	Path   string           `json:"path,omitzero"`
	Items  []ProvenanceFact `json:"items"`
	Total  int              `json:"total"`
	Limit  int              `json:"limit"`
	Offset int              `json:"offset"`
}

ProvenancePage binds origin history to a transactionally consistent node. Path is empty when the node is in trash.

type ProvenanceSource

type ProvenanceSource struct {
	Kind        string     `json:"kind"`
	Description string     `json:"description"`
	Reference   string     `json:"reference"`
	ModifiedAt  *time.Time `json:"modified_at,omitempty"`
}

ProvenanceSource describes an application-neutral origin for one immutable document creation. Reference may be a URI, archive key, filesystem path, or another stable source-local identifier; Docbank does not interpret it.

type PutOptions

type PutOptions struct {
	MediaType string
	Expected  *ContentIdentity
}

PutOptions controls one embedded content write. Expected is optional; when present, no node or version authority is granted unless both fields match the independently computed durable bytes.

type PutReceipt

type PutReceipt struct {
	Node            Node            `json:"node"`
	Version         ContentVersion  `json:"version"`
	Computed        ContentIdentity `json:"computed"`
	Physical        PhysicalContent `json:"physical"`
	Created         bool            `json:"created"`
	PhysicalCreated bool            `json:"physical_created"`
	Replaced        bool            `json:"replaced"`
}

PutReceipt proves the computed identity and resulting logical authority.

type RepackOptions

type RepackOptions struct {
	Budget       WorkBudget
	MinAge       time.Duration
	MinDeadBytes int64
}

type RepackReport

type RepackReport struct {
	MaintenanceProgress

	MappingsPruned         int64 `json:"mappings_pruned"`
	PacksSelected          int   `json:"packs_selected"`
	PacksRewritten         int   `json:"packs_rewritten"`
	PacksSealed            int   `json:"packs_sealed"`
	PacksRemoved           int   `json:"packs_removed"`
	PacksDeferredOversized int   `json:"packs_deferred_oversized"`
	BlobsRepacked          int   `json:"blobs_repacked"`
	BytesRepacked          int64 `json:"bytes_repacked"`
	BudgetExhausted        bool  `json:"budget_exhausted"`
}

RepackReport summarizes one bounded immutable-pack reclamation pass.

type RepairReceipt

type RepairReceipt struct {
	Computed            ContentIdentity `json:"computed"`
	Physical            PhysicalContent `json:"physical"`
	ReferencesPreserved int64           `json:"references_preserved"`
}

RepairReceipt proves the replacement bytes and reports the resulting physical authority without changing any logical node or version.

type ResetOptions

type ResetOptions struct {
	DiagnosticRoot string
	ReleaseCurrent func() error
}

ResetOptions defines the explicit move-aside boundary for ResetVault. ReleaseCurrent, when set, is called exactly once after reset excludes every overlapping hierarchy-owner acquisition and validates both paths, but before it takes ordinary ownership of the source directory. Embedded applications use it to hand an already-open vault and any surrounding lifecycle state to reset without an ownership gap.

type RevisionOptions

type RevisionOptions struct {
	IfRevision int64 `json:"if_revision,omitzero"`
}

RevisionOptions applies an optional lost-update guard to one tree mutation. Zero is unconditional; a positive value must match the node's revision.

type StoreBinding

type StoreBinding struct {
	Kind              string
	Path              string
	Endpoint          string
	Region            string
	Bucket            string
	Prefix            string
	CredentialProfile string
	Priority          int
	ForcePathStyle    bool
}

StoreBinding configures one embedded secondary namespace without exposing Kit backend types through Docbank's public API.

type TrashEmptyOptions

type TrashEmptyOptions struct {
	OlderThan time.Duration `json:"older_than"`
	MaxRoots  int           `json:"max_roots,omitzero"`
	DryRun    bool          `json:"dry_run"`
}

TrashEmptyOptions bounds one trash-empty preview or execution. A zero MaxRoots uses DefaultTrashEmptyMaxRoots. DryRun never deletes candidates.

type TrashEmptyReport

type TrashEmptyReport struct {
	Candidates int64 `json:"candidates"`
	Deleted    int64 `json:"deleted"`
	More       bool  `json:"more"`
	DryRun     bool  `json:"dry_run"`
}

TrashEmptyReport summarizes one bounded batch of eligible trash roots.

type Vault

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

Vault is one independently locked Docbank namespace. Separate Vault values may be open concurrently when their roots do not overlap.

func New

func New(ctx context.Context, config Config) (_ *Vault, retErr error)

New creates or opens one embedded vault and holds its exclusive hierarchy lock until Close. A standalone daemon or another embedded instance cannot own the same or an overlapping vault concurrently.

func ResetVault

func ResetVault(
	ctx context.Context, config Config, opts ResetOptions,
) (fresh *Vault, retErr error)

ResetVault atomically moves an existing vault to an absent diagnostic sibling and creates a fresh vault at the original canonical path. It never opens the source catalog and never deletes the source, diagnostic, or a partially initialized fresh vault. The returned fresh vault retains ordinary exclusive hierarchy ownership until Close.

func (*Vault) BatchMove

func (v *Vault) BatchMove(
	ctx context.Context, moves []BatchMoveItem,
) ([]BatchMoveReceipt, error)

BatchMove validates and applies one final-state reorganization as a single metadata transaction. Results preserve request order. Path sources resolve inside the transaction; stable node sources require a positive revision.

func (*Vault) Children

func (v *Vault) Children(
	ctx context.Context, directoryID int64, opts ChildrenOptions,
) (ChildrenPage, error)

Children lists one bounded page of a directory's live children, directories first and then files, name-sorted within each kind.

func (*Vault) Close

func (v *Vault) Close() error

Close waits for active operations and readers, then releases storage and the vault hierarchy lock. It is safe to call more than once.

func (*Vault) Create

func (v *Vault) Create(
	ctx context.Context, virtualPath string, content io.Reader, opts CreateOptions,
) (PutReceipt, error)

Create stores content only when virtualPath is absent. An identical retry, including any supplied provenance, returns the existing node and version; any different existing authority returns ErrContentConflict without appending history.

func (*Vault) EmptyTrash

func (v *Vault) EmptyTrash(
	ctx context.Context, opts TrashEmptyOptions,
) (TrashEmptyReport, error)

EmptyTrash previews or hard-deletes one finite batch of eligible trash roots. Subtrees cascade with their selected root; candidate and deletion counts therefore describe roots, not every descendant row.

func (*Vault) GarbageCollect

func (v *Vault) GarbageCollect(ctx context.Context, opts GCOptions) (GCReport, error)

GarbageCollect previews or removes one bounded canonical-hash page of unreachable catalog authority. The daemon separately reconciles physical orphan files for its legacy full-maintenance endpoint.

func (*Vault) ID

func (v *Vault) ID() string

ID reports the stable logical vault identity preserved by metadata export, backup, and restore. It is independent of the vault's filesystem root.

func (*Vault) LooseBacklog

func (v *Vault) LooseBacklog(ctx context.Context) (LooseBacklog, error)

LooseBacklog reports indexed loose content eligible for explicit packing.

func (*Vault) MovePath

func (v *Vault) MovePath(
	ctx context.Context, from, to string, opts RevisionOptions,
) (MutationReceipt, error)

MovePath renames or reparents one live path and returns its canonical new path. A positive IfRevision must match the source node exactly.

func (*Vault) OpenContent

func (v *Vault) OpenContent(ctx context.Context, virtualPath string) (*Content, error)

OpenContent opens the current catalog-authorized bytes for a live file. The reader holds a vault lease until Close; bytes are authoritative only after terminal io.EOF or a successful Verify.

func (*Vault) OpenVersionContent

func (v *Vault) OpenVersionContent(ctx context.Context, versionID string) (*VersionContent, error)

OpenVersionContent opens the catalog-authorized bytes for one immutable content version. The reader holds a vault lease and uses the same verified read contract as OpenContent.

func (*Vault) Pack

func (v *Vault) Pack(ctx context.Context, opts PackOptions) (PackReport, error)

Pack explicitly moves authorized loose content into managed immutable packs. It also performs the same reconciliation and repair pass as the standalone storage pack operation. Ordinary Put calls remain loose until Pack is called.

func (*Vault) Provenance

func (v *Vault) Provenance(
	ctx context.Context, nodeID int64, opts ProvenanceOptions,
) (ProvenancePage, error)

Provenance returns one bounded page of immutable origin facts for a file. The node, live path, count, and page come from one metadata snapshot. Path is empty when nodeID is in trash.

func (*Vault) Put

func (v *Vault) Put(
	ctx context.Context, virtualPath string, content io.Reader, opts PutOptions,
) (PutReceipt, error)

Put stores a reader at an absolute virtual file path. Missing parent directories are created. An unchanged retry converges on the current version; changed bytes create a new immutable version on the same node.

func (*Vault) Repack

func (v *Vault) Repack(ctx context.Context, opts RepackOptions) (RepackReport, error)

Repack retires dead packs and rewrites eligible sparse packs within one bounded pass while preserving Kit's soft raw-byte budget.

func (*Vault) RepairContent

func (v *Vault) RepairContent(
	ctx context.Context, identity ContentIdentity, trusted io.Reader,
) (RepairReceipt, error)

RepairContent replaces the physical bytes for one existing content identity after fully verifying trusted against its required SHA-256 and size. All nodes and historical versions keep referencing the same immutable identity.

func (*Vault) Restore

func (v *Vault) Restore(
	ctx context.Context, nodeID int64, opts RevisionOptions,
) (MutationReceipt, error)

Restore returns a trash root to its recorded origin, or to the canonical conflict-suffixed path selected by the store. A positive IfRevision must match the trashed node exactly.

func (*Vault) SQLiteDriver

func (v *Vault) SQLiteDriver() string

SQLiteDriver reports the adapter selected for this vault.

func (*Vault) Stat

func (v *Vault) Stat(ctx context.Context, virtualPath string) (Node, error)

Stat resolves a live virtual path to its stable node projection.

func (*Vault) TrashPath

func (v *Vault) TrashPath(
	ctx context.Context, path string, opts RevisionOptions,
) (MutationReceipt, error)

TrashPath moves one live path and its subtree to trash, returning the canonical pre-trash path. A positive IfRevision must match the root node.

func (*Vault) Verify

func (v *Vault) Verify(ctx context.Context, opts VerifyOptions) (VerifyReport, error)

Verify validates one bounded canonical-hash page of catalog-authorized content. Whole-catalog metadata validation remains daemon-only.

func (*Vault) Versions

func (v *Vault) Versions(
	ctx context.Context, nodeID int64, opts VersionsOptions,
) (VersionsPage, error)

func (*Vault) Walk

func (v *Vault) Walk(ctx context.Context, rootPath string, opts WalkOptions) (*Walker, error)

Walk begins a stable snapshot traversal rooted at rootPath.

type VerifiedReadCloser

type VerifiedReadCloser interface {
	io.ReadCloser
	Verify() error
}

VerifiedReadCloser is a bounded-memory content reader. A caller must reach terminal io.EOF or call Verify successfully before treating bytes as valid; an early Close reports incomplete verification and never drains implicitly.

type VerifyOptions

type VerifyOptions struct{ Budget WorkBudget }

type VerifyProblem

type VerifyProblem struct {
	Hash    string `json:"hash"`
	Problem string `json:"problem"`
}

type VerifyReport

type VerifyReport struct {
	MaintenanceProgress

	OK               int             `json:"ok"`
	Problems         []VerifyProblem `json:"problems,omitempty"`
	MetadataProblems []string        `json:"metadata_problems,omitempty"`
}

VerifyReport summarizes one bounded content verification pass. The metadata field remains for compatibility with the daemon's full verification report.

type VersionContent

type VersionContent struct {
	Version ContentVersion
	Reader  VerifiedReadCloser
}

VersionContent binds a verified byte stream to one immutable content version.

type VersionsOptions

type VersionsOptions struct {
	Limit  int
	Offset int
}

type VersionsPage

type VersionsPage struct {
	Items  []ContentVersion `json:"items"`
	Total  int              `json:"total"`
	Limit  int              `json:"limit"`
	Offset int              `json:"offset"`
}

type WalkEntry

type WalkEntry struct {
	Path string
	Node Node
}

WalkEntry is one node and its canonical path in the traversal snapshot.

type WalkOptions

type WalkOptions struct {
	PageSize       int
	IncludeTrashed bool
}

WalkOptions controls one stable snapshot traversal.

type Walker

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

Walker returns bounded pages from one stable tree snapshot until closed.

func (*Walker) Close

func (w *Walker) Close() error

Close releases the snapshot and vault lifecycle lease. It is idempotent.

func (*Walker) Next

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

Next returns the next bounded snapshot page. io.EOF follows the last page.

type WorkBudget

type WorkBudget struct {
	MaxObjects int
	MaxBytes   int64
	Cursor     string
}

WorkBudget bounds one embedded maintenance pass. MaxObjects zero uses DefaultMaintenanceMaxObjects and values above MaxMaintenanceObjects are rejected. MaxBytes zero is unlimited; a positive byte limit is soft, so one selected object may carry the pass over the limit.