database

package
v0.1.0-alpha.13 Latest Latest
Warning

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

 Go to latest Published: Jul 24, 2026 License: Apache-2.0 Imports: 33 Imported by: 0

Documentation

Overview

Package database implements the Meldbase database API behind the module-root public package.

Index

Constants

View Source 
const (
	IndexBuildPhaseScan    IndexBuildPhase = "scan"
	IndexBuildPhaseCatchUp IndexBuildPhase = "catch_up"
	IndexBuildPhaseReady   IndexBuildPhase = "ready"
	IndexBuildPhaseFailed  IndexBuildPhase = "failed"

	IndexBuildFailureNone           IndexBuildFailure = ""
	IndexBuildFailureUniqueConflict IndexBuildFailure = "unique_conflict"
	IndexBuildFailureResourceLimit  IndexBuildFailure = "resource_limit"
	IndexBuildFailureHistoryLost    IndexBuildFailure = "history_lost"
	IndexBuildFailureCanceled       IndexBuildFailure = "canceled"
	IndexBuildFailureInvalidIndex   IndexBuildFailure = "invalid_index"
)
View Source 
const (
	DefaultCommitCoordinatorMaxBatch   = 32
	DefaultCommitCoordinatorMaxPending = 1024
)
View Source 
const (
	PageSize            uint64 = 16 << 10
	DefaultMaxFileBytes uint64 = 8 << 30
)
View Source 
const (
	DefaultCommitRetentionMaxCommits uint64 = 10_000
	DefaultCommitRetentionMaxBytes   uint64 = 256 << 20
	// DefaultReplayDeliveryTimeout bounds how long a replay source can wait
	// for a full caller buffer before it releases the retained-history lease.
	DefaultReplayDeliveryTimeout = 5 * time.Second
)
View Source 
const (
	ReplicationHelloFrame  = "hello"
	ReplicationBatchFrame  = "batch"
	ReplicationAckFrame    = "ack"
	ReplicationResyncFrame = "resync_required"
)
View Source 
const (
	DefaultMaxDocumentBytes      uint64 = 16 << 20
	DefaultMaxTransactionBytes   uint64 = 64 << 20
	DefaultMaxTransactionChanges uint64 = 10_000
	DefaultMaxIndexBuildEntries  uint64 = 1_000_000
	DefaultMaxIndexBuildBytes    uint64 = 256 << 20
	// Reactive views retain matching document versions for incremental ordering
	// and updates, not merely the page currently emitted to a subscriber.
	DefaultMaxReactiveViewDocuments  uint64 = 10_000
	DefaultMaxReactiveViewBytes      uint64 = 64 << 20
	DefaultMaxQueryDocumentsExamined uint64 = 100_000
	DefaultMaxQueryKeysExamined      uint64 = 100_000
	DefaultMaxQueryCandidates        uint64 = 100_000
	DefaultMaxQuerySortBytes         uint64 = 64 << 20
	DefaultMaxQuerySkip              uint64 = 100_000
	// Predicate steps account for residual expression visits and data-dependent
	// comparisons such as scalar membership within stored arrays. It bounds
	// CPU work that document/key scan limits alone cannot see.
	DefaultMaxQueryPredicateSteps uint64 = 10_000_000
)
View Source 
const DefaultCommitCoordinatorMaxDelay = time.Millisecond
View Source 
const (
	DefaultReplicationMaxFrameBytes = 96 << 20
)
View Source 
const DefaultRollbackAnchorOperationTimeout = 10 * time.Second

DefaultRollbackAnchorOperationTimeout prevents a failed remote trust service from indefinitely holding database publication acknowledgement.

View Source 
const ReplicationProtocolVersion = 1

ReplicationProtocolVersion is intentionally separate from the browser realtime protocol. It transports durable database positions between trusted servers, not end-user query subscriptions.

Variables

View Source 
var (
	ErrClosed                            = errors.New("meldbase: database is closed")
	ErrInvalidDocument                   = errors.New("meldbase: invalid document")
	ErrInvalidFilter                     = errors.New("meldbase: invalid filter")
	ErrInvalidUpdate                     = errors.New("meldbase: invalid update")
	ErrMutationLimit                     = errors.New("meldbase: mutation affected-row limit exceeded")
	ErrWriteConflict                     = errors.New("meldbase: write transaction snapshot conflicted")
	ErrWriteTransactionUnsupported       = errors.New("meldbase: write transactions require a durable database")
	ErrNotFound                          = errors.New("meldbase: document not found")
	ErrDuplicateID                       = errors.New("meldbase: duplicate document id")
	ErrInvalidCollection                 = errors.New("meldbase: invalid collection")
	ErrImmutableID                       = errors.New("meldbase: _id is immutable")
	ErrSlowConsumer                      = errors.New("meldbase: change consumer is too slow")
	ErrCorrupt                           = errors.New("meldbase: corrupt database")
	ErrUnsupportedFormat                 = errors.New("meldbase: unsupported storage format or required feature")
	ErrDuplicateKey                      = errors.New("meldbase: duplicate index key")
	ErrInvalidIndex                      = errors.New("meldbase: invalid index")
	ErrCompoundIndexUnsupported          = errors.New("meldbase: compound or descending indexes are unsupported")
	ErrDurability                        = errors.New("meldbase: durability failure; writes are disabled")
	ErrInvalidDelta                      = errors.New("meldbase: invalid query delta")
	ErrHistoryLost                       = errors.New("meldbase: requested history is no longer retained")
	ErrDestinationExists                 = errors.New("meldbase: destination already exists")
	ErrCompactionUnsupported             = errors.New("meldbase: compaction requires an open durable database")
	ErrCompactionDestinationExists       = errors.New("meldbase: compaction destination already exists")
	ErrReclamationUnsupported            = errors.New("meldbase: page reclamation requires an open durable database")
	ErrInvalidReclamationOptions         = errors.New("meldbase: invalid reclamation options")
	ErrReclamationConflict               = errors.New("meldbase: online reclamation conflicted with concurrent writes")
	ErrBackupUnsupported                 = errors.New("meldbase: physical backup requires an open durable database")
	ErrBackupDestinationExists           = errors.New("meldbase: backup destination already exists or is the source")
	ErrLogicalArchiveUnsupported         = errors.New("meldbase: logical archive requires an open durable database")
	ErrLogicalArchiveDestinationExists   = errors.New("meldbase: logical archive destination already exists or is the source")
	ErrVerificationUnsupported           = errors.New("meldbase: verification requires an existing database")
	ErrDatabaseLocked                    = errors.New("meldbase: database is locked by another process")
	ErrRollbackDetected                  = errors.New("meldbase: database rollback detected")
	ErrDatabaseIdentity                  = errors.New("meldbase: unexpected database identity")
	ErrInsecureFileMode                  = errors.New("meldbase: database file permissions are not owner-private")
	ErrRollbackAnchorRequired            = errors.New("meldbase: rollback anchor is missing; explicit initialization is required")
	ErrRollbackAnchor                    = errors.New("meldbase: rollback anchor durability failure")
	ErrInvalidRollbackProtection         = errors.New("meldbase: invalid rollback protection options")
	ErrRecoveryRequired                  = errors.New("meldbase: startup recovery required by the selected policy")
	ErrInvalidResourceLimits             = errors.New("meldbase: invalid resource limits")
	ErrResourceLimit                     = errors.New("meldbase: resource limit exceeded")
	ErrQueryBudget                       = errors.New("meldbase: query execution budget exceeded")
	ErrIndexBuildUnsupported             = errors.New("meldbase: resumable index builds require a durable database")
	ErrIndexBuildNotFound                = errors.New("meldbase: index build not found")
	ErrIndexBuildExists                  = errors.New("meldbase: index build already exists")
	ErrIndexBuildFailed                  = errors.New("meldbase: index build is in a terminal failed state")
	ErrInvalidIndexBuildSchedulerOptions = errors.New("meldbase: invalid index build scheduler options")
	ErrIndexBuildSchedulerRunning        = errors.New("meldbase: index build scheduler already running")
	ErrInvalidCommitCoordinatorOptions   = errors.New("meldbase: invalid commit coordinator options")
	ErrInvalidReplayDeliveryTimeout      = errors.New("meldbase: invalid replay delivery timeout")
	ErrDurableConsumerUnsupported        = errors.New("meldbase: durable change consumers require a durable database")
	ErrDurableConsumerExists             = errors.New("meldbase: durable change consumer already exists")
	ErrDurableConsumerNotFound           = errors.New("meldbase: durable change consumer not found")
	ErrReplicaReadOnly                   = errors.New("meldbase: follower is read-only")
	ErrReplicaSequence                   = errors.New("meldbase: follower change token is not the next sequence")
	ErrReplicaProtocol                   = errors.New("meldbase: invalid replication protocol frame")
	ErrReplicaSourceActive               = errors.New("meldbase: replication source consumer already has an active session")
	ErrReplicaPromotionAuthority         = errors.New("meldbase: follower promotion requires an external fencing authority")
	ErrReplicaPromotionFence             = errors.New("meldbase: follower promotion fence does not match local state")
	ErrReplicaPromotionWriteFence        = errors.New("meldbase: follower promotion requires a configured primary write fence")
	ErrReplicaPromoted                   = errors.New("meldbase: follower has been promoted and no longer accepts replication")
	ErrPrimaryWriteFence                 = errors.New("meldbase: primary write fence rejected the commit")
	// ErrCommitOutcomeUnknown means cancellation or a lost caller connection
	// raced an already-admitted durable write. Callers must reconcile by the
	// returned document ID(s), rather than retrying business logic blindly.
	ErrCommitOutcomeUnknown = errors.New("meldbase: commit outcome is unknown; do not retry blindly")
)
View Source 
var DefaultQueryLimits = QueryLimits{
	MaxWireBytes: 1 << 20, MaxDepth: 16, MaxNodes: 128,
	MaxArrayItems: 256, MaxValueBytes: 16_384, MaxSortFields: 4,
	MaxLimit: 10_000,
}
View Source 
var (
	ErrDiagnosticsActive = errors.New("meldbase: diagnostics are already active")
)

Functions

func MarshalQuerySpecJSON 

func MarshalQuerySpecJSON(query QuerySpec) ([]byte, error)

MarshalQuerySpecJSON emits the canonical, data-only wire representation used for transport fingerprints and cross-language conformance.

func MarshalReplicationFrame 

func MarshalReplicationFrame(frame ReplicationFrame, limits ReplicationFrameLimits) ([]byte, error)

MarshalReplicationFrame returns a strict JSON frame with canonical document images encoded as base64 of the storage-independent typed document codec. It is suitable for WebSocket binary/text messages, QUIC streams or framed RPC, but it does not provide authentication or encryption itself.

func MarshalWireDocument 

func MarshalWireDocument(document Document) ([]byte, error)

func MarshalWireValue 

func MarshalWireValue(value Value) ([]byte, error)

func ValidateStrictJSON 

func ValidateStrictJSON(data []byte, maxBytes int) error

ValidateStrictJSON rejects oversized, trailing, deeply nested, and duplicate-key JSON before a transport decodes it into structs or maps.

Types

type ArchiveBootstrap 

type ArchiveBootstrap struct {
	Backup          BackupResult
	CheckpointToken uint64
	SnapshotToken   uint64
}

ArchiveBootstrap binds an exact verified physical snapshot to the durable database change feed that was pinned before that snapshot began.

A receiver must persist and verify Backup, then drain and Ack every batch up through SnapshotToken without applying it (the snapshot already contains those effects). It can then apply and Ack later batches in order. This avoids the bootstrap/tail gap without inventing a second, weaker history contract.

type BackupResult 

type BackupResult struct {
	Bytes          uint64 `json:"bytes"`
	Pages          uint64 `json:"pages"`
	CommitSequence uint64 `json:"commitSequence"`
	MetaGeneration uint64 `json:"metaGeneration"`
	DatabaseIDHex  string `json:"databaseIdHex"`
	SHA256         string `json:"sha256"`
}

func ImportPhysicalBackup 

func ImportPhysicalBackup(ctx context.Context, source io.Reader, destination string, expected BackupResult, options PhysicalBackupImportOptions) (BackupResult, error)

ImportPhysicalBackup receives one exact Backup artifact into a new local path. It writes a private temporary file, checks the claimed byte count and SHA-256 while streaming, runs the complete offline graph/index verifier, then publishes with the same no-overwrite link-and-directory-sync commit point as backup and migration.

source is intentionally transport-neutral. A WebSocket, HTTP response, QUIC stream, or removable-media reader may supply it, but transport cancellation must close or honor ctx itself: a generic io.Reader cannot be interrupted while blocked in Read. The destination is never opened as a writable DB by this function; callers normally open the successfully imported file through OpenFollower before applying a replication tail.

type BackupStats 

type BackupStats struct {
	Active       uint64        `json:"active"`
	Attempts     uint64        `json:"attempts"`
	Completed    uint64        `json:"completed"`
	Failed       uint64        `json:"failed"`
	LastBytes    uint64        `json:"lastBytes"`
	LastDuration time.Duration `json:"lastDurationNanos"`
}

type Change 

type Change struct {
	Collection string
	Operation  Operation
	DocumentID DocumentID
	Before     *Document
	After      *Document
	Index      *IndexDefinition

	// ChangedPaths is the sorted, deduplicated set of document paths changed by
	// an Update operation when the writer can prove it. A nil value means the
	// changed field set is unknown and consumers must conservatively treat the
	// whole document as affected. Insert, delete and catalog changes intentionally
	// use that conservative form: their membership and visible payload may change
	// through any query path.
	//
	// The slice is immutable once a Change enters the dispatcher. Public watcher
	// deliveries receive an independent copy via cloneChange.
	ChangedPaths []string
	// contains filtered or unexported fields
}

type ChangeBatch 

type ChangeBatch struct {
	Token   uint64
	Changes []Change
}

type Collection 

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

func (*Collection) CreateIndex 

func (c *Collection) CreateIndex(ctx context.Context, name string, fields []IndexField, options IndexOptions) error

func (*Collection) CreateIndexOnline 

func (c *Collection) CreateIndexOnline(ctx context.Context, name string, fields []IndexField, options IndexOptions) (IndexBuildID, error)

CreateIndexOnline starts and runs one durable build to publication. A context cancellation leaves the returned build discoverable through IndexBuilds; use StartIndexBuild when the ID must be known before execution.

func (*Collection) DeleteMany 

func (c *Collection) DeleteMany(ctx context.Context, filter Filter) (DeleteResult, error)

func (*Collection) DeleteManyQuery 

func (c *Collection) DeleteManyQuery(ctx context.Context, query QuerySpec) (DeleteResult, error)

func (*Collection) DeleteManyQueryLimited 

func (c *Collection) DeleteManyQueryLimited(ctx context.Context, query QuerySpec, maxAffected int) (DeleteResult, error)

DeleteManyQueryLimited atomically rejects the whole mutation when more than maxAffected documents match.

func (*Collection) DeleteOne 

func (c *Collection) DeleteOne(ctx context.Context, filter Filter) (DeleteResult, error)

func (*Collection) DeleteOneQuery 

func (c *Collection) DeleteOneQuery(ctx context.Context, query QuerySpec) (DeleteResult, error)

func (*Collection) Explain 

func (c *Collection) Explain(ctx context.Context, filter Filter) (ExplainResult, error)

func (*Collection) ExplainQuery 

func (c *Collection) ExplainQuery(ctx context.Context, query QuerySpec) (ExplainResult, error)

ExplainQuery accepts the same validated compiled query used by FindQuery, so Explain cannot silently omit sort, skip, limit, or seek options.

func (*Collection) ExplainWithOptions 

func (c *Collection) ExplainWithOptions(ctx context.Context, filter Filter, options QueryOptions) (ExplainResult, error)

ExplainWithOptions compiles a filter and its ordering/window options before returning the selected plan. It is the convenience counterpart to ExplainQuery for callers that do not already hold a compiled QuerySpec.

func (*Collection) Find 

func (c *Collection) Find(ctx context.Context, filter Filter, options ...QueryOptions) (*Cursor, error)

func (*Collection) FindOne 

func (c *Collection) FindOne(ctx context.Context, filter Filter) (Document, error)

func (*Collection) FindQuery 

func (c *Collection) FindQuery(ctx context.Context, query QuerySpec) (*Cursor, error)

func (*Collection) InsertMany 

func (c *Collection) InsertMany(ctx context.Context, documents []Document) ([]DocumentID, error)

InsertMany validates IDs, documents, and all unique-index keys before writing one WAL record. Either the entire batch becomes visible or none of it does.

func (*Collection) InsertOne 

func (c *Collection) InsertOne(ctx context.Context, document Document) (DocumentID, error)

func (*Collection) RebuildIndexOnline 

func (c *Collection) RebuildIndexOnline(ctx context.Context, name string, fields []IndexField, options IndexOptions) (IndexBuildID, error)

RebuildIndexOnline starts and runs an atomic replacement for an existing durable index. A cancellation leaves the old index published and the private replacement discoverable through IndexBuilds.

func (*Collection) SnapshotQuery 

func (c *Collection) SnapshotQuery(ctx context.Context, query QuerySpec) (QuerySnapshot, error)

func (*Collection) StartIndexBuild 

func (c *Collection) StartIndexBuild(ctx context.Context, name string, fields []IndexField, options IndexOptions) (IndexBuildID, error)

StartIndexBuild creates a durable private shadow index. It is Storage only and does not scan documents or make the index query-visible.

func (*Collection) StartIndexRebuild 

func (c *Collection) StartIndexRebuild(ctx context.Context, name string, fields []IndexField, options IndexOptions) (IndexBuildID, error)

StartIndexRebuild creates a durable private shadow index that will atomically replace an already-published index with the same name. The old index remains query-visible until final publication; the build is resumable or abortable.

func (*Collection) SubscribeQuery 

func (c *Collection) SubscribeQuery(ctx context.Context, query QuerySpec, buffer int) (*QuerySubscription, error)

func (*Collection) SubscribeQueryDeltas 

func (c *Collection) SubscribeQueryDeltas(ctx context.Context, query QuerySpec, buffer int) (*QueryDeltaSubscription, error)

func (*Collection) UpdateMany 

func (c *Collection) UpdateMany(ctx context.Context, filter Filter, update Update) (UpdateResult, error)

func (*Collection) UpdateManyQuery 

func (c *Collection) UpdateManyQuery(ctx context.Context, query QuerySpec, mutation MutationSpec) (UpdateResult, error)

func (*Collection) UpdateManyQueryLimited 

func (c *Collection) UpdateManyQueryLimited(ctx context.Context, query QuerySpec, mutation MutationSpec, maxAffected int) (UpdateResult, error)

UpdateManyQueryLimited atomically rejects the whole mutation when more than maxAffected documents match. A non-positive limit is invalid here so callers cannot accidentally disable a server-owned safety bound.

func (*Collection) UpdateOne 

func (c *Collection) UpdateOne(ctx context.Context, filter Filter, update Update) (UpdateResult, error)

func (*Collection) UpdateOneQuery 

func (c *Collection) UpdateOneQuery(ctx context.Context, query QuerySpec, mutation MutationSpec) (UpdateResult, error)

type CommitCoordinatorOptions 

type CommitCoordinatorOptions struct {
	Enabled    bool
	MaxBatch   int
	MaxPending int
	MaxDelay   time.Duration
}

CommitCoordinatorOptions controls optional group commit for ordinary InsertMany, filter Update and filter Delete operations. It is disabled by default, so opening an existing database never changes write scheduling unexpectedly.

A coordinator group has one physical Meta publication but retains one logical commit token for every admitted write request. Public write transactions, atomic RPC, index builds and other maintenance operations remain exclusive commits. When rollback protection is configured, the coordinator advances the external anchor only after the group's final Meta publication is durable and before acknowledging any member.

type CommitCoordinatorStats 

type CommitCoordinatorStats struct {
	Enabled             bool   `json:"enabled"`
	Pending             uint64 `json:"pending"`
	PendingCapacity     uint64 `json:"pendingCapacity"`
	Admitted            uint64 `json:"admitted"`
	AdmissionRejected   uint64 `json:"admissionRejected"`
	Batches             uint64 `json:"batches"`
	GroupedTransactions uint64 `json:"groupedTransactions"`
	OutcomeUnknown      uint64 `json:"outcomeUnknown"`
}

CommitCoordinatorStats is a fixed-cardinality snapshot of the optional 

write-admission scheduler. It is included in DBStats and the versioned

admin schema, so applications can alert on admission pressure without inspecting a mutable queue or adding application labels.

type CommitRetentionPolicy 

type CommitRetentionPolicy struct {
	MaxCommits uint64
	MaxBytes   uint64
}

CommitRetentionPolicy bounds logical Commit Log history by both commit count and canonical encoded bytes. Zero fields select production defaults. Active replay leases may temporarily exceed either budget rather than losing history under a reader.

type CommitStats 

type CommitStats struct {
	Total   uint64 `json:"total"`
	Changes uint64 `json:"changes"`
}

type CompactionOptions 

type CompactionOptions struct {
	StorageLimits  StorageLimits
	ResourceLimits ResourceLimits
}

CompactionOptions configures newly written replacement or compaction files. ResourceLimits govern transient index construction as well as the reopened destination handle; zero fields select production defaults.

type CompactionStats 

type CompactionStats struct {
	Active       uint64        `json:"active"`
	Attempts     uint64        `json:"attempts"`
	Completed    uint64        `json:"completed"`
	Failed       uint64        `json:"failed"`
	InputBytes   uint64        `json:"inputBytes"`
	OutputBytes  uint64        `json:"outputBytes"`
	LastDuration time.Duration `json:"lastDurationNanos"`
}

type Cursor 

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

func (*Cursor) All 

func (c *Cursor) All(ctx context.Context) ([]Document, error)

func (*Cursor) Close 

func (c *Cursor) Close() error

Close releases a pinned storage snapshot held by a lazy cursor. It is safe to call repeatedly. Exhaustion, limit completion, errors and context cancellation close automatically; callers that stop early must close explicitly.

func (*Cursor) Next 

func (c *Cursor) Next(ctx context.Context) (Document, bool, error)

type DB 

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

func New 

func New() *DB

func NewWithOptions 

func NewWithOptions(options DatabaseOptions) (*DB, error)

NewWithOptions creates an in-memory database with explicit resource limits.

func Open 

func Open(path string) (*DB, error)

Open creates or opens a Meldbase durable database in the current format.

func OpenWithOptions 

func OpenWithOptions(path string, options OpenOptions) (*DB, error)

func (*DB) AbortIndexBuild 

func (db *DB) AbortIndexBuild(ctx context.Context, id IndexBuildID) error

func (*DB) AcquireReplicationSourceLease 

func (db *DB) AcquireReplicationSourceLease(name string) (*ReplicationSourceLease, error)

AcquireReplicationSourceLease reserves name until Release. Callers must authenticate and derive name outside untrusted replication frames. The lease is intentionally DB-local: a database file already has one writer process, while primary election remains an external control-plane responsibility.

func (*DB) Backup 

func (db *DB) Backup(ctx context.Context, destination string) (result BackupResult, resultErr error)

Backup writes an exact, verified physical copy to a new path. It preserves database identity and Commit Log history, so the result is a restore artifact rather than an independent writable fork. The source writer is blocked for the copy duration; readers remain available.

func (*DB) BeginArchive 

func (db *DB) BeginArchive(ctx context.Context, name, destination string, buffer int) (ArchiveBootstrap, *DurableDatabaseChangeSubscription, error)

BeginArchive creates a durable database-wide checkpoint and a verified physical snapshot. The checkpoint is established first, so Commit Log retention preserves every token needed to bridge from CheckpointToken to the returned SnapshotToken, even while writes continue before the snapshot's short read barrier begins.

This is deliberately a transport-neutral bootstrap primitive. It does not copy files to another machine, open a writable follower, or acknowledge a token on the caller's behalf. Those actions have different ownership and failure domains and must be explicit in the eventual wire protocol.

func (*DB) CanResumeFrom 

func (db *DB) CanResumeFrom(token uint64) bool

func (*DB) Close 

func (db *DB) Close() error

func (*DB) Collection 

func (db *DB) Collection(name string) *Collection

func (*DB) CommitCoordinatorStats 

func (db *DB) CommitCoordinatorStats() CommitCoordinatorStats

CommitCoordinatorStats returns a bounded snapshot of the optional admission scheduler. It performs no I/O. DBStats includes the same snapshot in the versioned admin schema; this method is convenient for direct callers.

func (*DB) Compact 

func (db *DB) Compact(ctx context.Context, destination string) (resultErr error)

Compact writes one current logical snapshot into a new, atomically published file. It never overwrites destination or mutates the source. Writes which commit after the source snapshot is pinned may continue and are intentionally absent from the destination. The compacted database receives a new identity and commit-log history, so callers must treat every old resume token as invalid.

func (*DB) CompactWithOptions 

func (db *DB) CompactWithOptions(ctx context.Context, destination string, options CompactionOptions) (resultErr error)

CompactWithOptions is Compact with an explicit destination quota.

func (*DB) CreateCollection 

func (db *DB) CreateCollection(ctx context.Context, name string) error

CreateCollection creates an empty durable collection. CRUD operations still create collections implicitly; this explicit form exists for schema tools that must preserve an otherwise-empty collection, such as logical import.

func (*DB) CreateDurableCollectionChanges 

func (db *DB) CreateDurableCollectionChanges(ctx context.Context, name, collection string, afterToken uint64, buffer int) (*DurableChangeSubscription, error)

CreateDurableCollectionChanges creates a durable, collection-scoped document feed at afterToken. The requested position must still be retained. A logical name may be reused for a different collection without collision; the storage checkpoint identity is derived from both values.

func (*DB) CreateDurableDatabaseChanges 

func (db *DB) CreateDurableDatabaseChanges(ctx context.Context, name string, afterToken uint64, buffer int) (*DurableDatabaseChangeSubscription, error)

CreateDurableDatabaseChanges creates a named durable feed after afterToken. The requested position must still be retained. Names share no namespace with collection-scoped consumers, so one application can use the same logical name for both an outbox and a database archive without a checkpoint clash.

func (*DB) DatabaseID 

func (db *DB) DatabaseID() [16]byte

DatabaseID returns the stable, non-secret database namespace used to bind resume and replication protocols. It is not an authentication token.

func (*DB) DatabaseIdentity 

func (db *DB) DatabaseIdentity() [16]byte

func (*DB) DeleteDurableCollectionChanges 

func (db *DB) DeleteDurableCollectionChanges(ctx context.Context, name, collection string) error

DeleteDurableCollectionChanges explicitly removes one retained checkpoint. Callers should stop every owner of that logical consumer first; an already open stream retains only its temporary process-local pin until it closes.

func (*DB) DeleteDurableDatabaseChanges 

func (db *DB) DeleteDurableDatabaseChanges(ctx context.Context, name string) error

DeleteDurableDatabaseChanges removes a named database-wide checkpoint. Stop all active owners first; deletion deliberately makes future resume fail.

func (*DB) DiagnosticSnapshotAfter 

func (db *DB) DiagnosticSnapshotAfter(after uint64, limit int) DiagnosticSnapshot

DiagnosticSnapshotAfter reads the currently active diagnostic session. It allows long-lived admin handlers to follow a safely replaced session.

func (*DB) EnableDiagnostics 

func (db *DB) EnableDiagnostics(options DiagnosticsOptions) (*Diagnostics, error)

func (*DB) ExportLogicalArchive 

func (db *DB) ExportLogicalArchive(ctx context.Context, destination string) (result LogicalArchiveResult, resultErr error)

ExportLogicalArchive writes a versioned JSON Lines snapshot that contains collections, typed documents and index definitions, but no pages, database identity or commit history. The source is pinned at one durable snapshot; writes committed after that point are deliberately absent.

func (*DB) IndexBuild 

func (db *DB) IndexBuild(id IndexBuildID) (IndexBuildStatus, error)

func (*DB) IndexBuilds 

func (db *DB) IndexBuilds() ([]IndexBuildStatus, error)

IndexBuilds returns all durable unfinished builds. The result survives a clean close, process crash, and reopen.

func (*DB) IndexCatalog 

func (db *DB) IndexCatalog(ctx context.Context) ([]IndexCatalogEntry, error)

IndexCatalog returns every published index in canonical collection/name order. The returned definitions and field slices are independent copies.

func (*DB) MeldbaseSystemRecordBackend 

func (db *DB) MeldbaseSystemRecordBackend() systemrecord.Backend

MeldbaseSystemRecordBackend is internal plumbing for first-party packages such as server. Its return type lives under internal/, so it is deliberately unavailable as an application-facing generic key/value API.

func (*DB) MeldbaseSystemWrite 

func (db *DB) MeldbaseSystemWrite(ctx context.Context, systemMutation systemrecord.Mutation, build func(*WriteTransaction) ([]byte, error)) (systemrecord.Result, bool, error)

MeldbaseSystemWrite runs build against one immutable snapshot without holding the database writer lock. If build succeeds and its point read set is still valid, its business changes and systemMutation commit in one generation. The bool reports whether a composite commit was attempted; false means build produced no business change or lost optimistic validation.

This method is first-party plumbing: the systemrecord parameter is internal, preventing external applications from using the private keyspace.

func (*DB) OpenDurableCollectionChanges 

func (db *DB) OpenDurableCollectionChanges(ctx context.Context, name, collection string, buffer int) (*DurableChangeSubscription, error)

OpenDurableCollectionChanges reopens an existing durable collection feed at its stored checkpoint. If retention cannot satisfy that position it returns ErrHistoryLost; it never silently starts from a newer token.

func (*DB) OpenDurableDatabaseChanges 

func (db *DB) OpenDurableDatabaseChanges(ctx context.Context, name string, buffer int) (*DurableDatabaseChangeSubscription, error)

OpenDurableDatabaseChanges resumes a named durable feed from its persisted checkpoint. ErrHistoryLost is returned instead of silently starting at a later token when the required Commit Log window is gone.

func (*DB) OpenQueryReplay 

func (db *DB) OpenQueryReplay(ctx context.Context, collection string, query QuerySpec, afterToken uint64, buffer int) (*QueryReplaySubscription, error)

func (*DB) OperationalState 

func (db *DB) OperationalState() OperationalState

func (*DB) ReclaimPages 

func (db *DB) ReclaimPages(ctx context.Context) (result ReclaimResult, resultErr error)

ReclaimPages audits both valid Meta roots and every active snapshot/replay lease, then makes only unreachable pages available to future COW commits. The free pool is process-local and safely reconstructed by another call on reopen.

func (*DB) ReclaimPagesWithOptions 

func (db *DB) ReclaimPagesWithOptions(ctx context.Context, options ReclaimOptions) (result ReclaimResult, resultErr error)

ReclaimPagesWithOptions runs explicit synchronous or low-pause optimistic reclamation. Online mode is opt-in and may return an error wrapping ErrReclamationConflict when every bounded attempt overlaps a commit.

func (*DB) RecoveryReport 

func (db *DB) RecoveryReport() RecoveryReport

RecoveryReport returns the receipt captured by the successful constructor. It performs no I/O and never changes after the DB is opened.

func (*DB) ResourceLimits 

func (db *DB) ResourceLimits() ResourceLimits

ResourceLimits returns the immutable normalized limits selected at open.

func (*DB) ResumeIndexBuild 

func (db *DB) ResumeIndexBuild(ctx context.Context, id IndexBuildID) error

ResumeIndexBuild scans bounded batches, catches up retained commits, and atomically publishes the index. Only one caller should resume a given build; stale concurrent callers receive ErrWriteConflict from durable CAS checks.

func (*DB) RunWriteTransaction 

func (db *DB) RunWriteTransaction(ctx context.Context, build func(*WriteTransaction) error) error

RunWriteTransaction executes build against one immutable Storage snapshot and atomically publishes all staged point mutations if every document read by the callback still matches. The callback runs without the database writer lock. A conflicting point write returns ErrWriteConflict; callbacks are never retried because they may contain application side effects.

A successful callback with no effective changes is a successful no-op and does not advance the commit sequence. The transaction is invalid as soon as the callback returns. Normal DB and Collection methods must not be called from inside build.

func (*DB) StartIndexBuildScheduler 

func (db *DB) StartIndexBuildScheduler(parent context.Context, options IndexBuildSchedulerOptions) (*IndexBuildScheduler, error)

func (*DB) StartMaintenance 

func (db *DB) StartMaintenance(parent context.Context, options MaintenanceOptions) (*Maintenance, error)

func (*DB) Stats 

func (db *DB) Stats() DBStats

func (*DB) Sync 

func (db *DB) Sync() error

Sync confirms the current durable state. Every successful write is already published and synced, so this is normally a cheap health check.

func (*DB) WatchChanges 

func (db *DB) WatchChanges(ctx context.Context, collection string, buffer int) (<-chan ChangeBatch, <-chan error, error)

type DBStats 

type DBStats struct {
	CapturedAt           time.Time     `json:"capturedAt"`
	StartedAt            time.Time     `json:"startedAt"`
	Uptime               time.Duration `json:"uptimeNanos"`
	Closed               bool          `json:"closed"`
	WritesDisabled       bool          `json:"writesDisabled"`
	Durable              bool          `json:"durable"`
	CommitSequence       uint64        `json:"commitSequence"`
	Collections          uint64        `json:"collections"`
	Documents            uint64        `json:"documents"`
	Indexes              uint64        `json:"indexes"`
	ActiveChangeWatchers uint64        `json:"activeChangeWatchers"`

	Commits           CommitStats            `json:"commits"`
	Transactions      WriteTransactionStats  `json:"writeTransactions"`
	Queries           QueryStats             `json:"queries"`
	Realtime          RealtimeStats          `json:"realtime"`
	CommitCoordinator CommitCoordinatorStats `json:"commitCoordinator"`
	PrimaryWriteFence PrimaryWriteFenceStats `json:"primaryWriteFence"`
	Durability        DurabilityStats        `json:"durability"`
	Storage           StorageStats           `json:"storage"`
	Compaction        CompactionStats        `json:"compaction"`
	Reclamation       ReclamationStats       `json:"reclamation"`
	Backup            BackupStats            `json:"backup"`
	Diagnostics       DiagnosticStats        `json:"diagnostics"`
	Recovery          RecoveryReport         `json:"recovery"`
	Resources         ResourceStats          `json:"resources"`
	IndexBuilds       IndexBuildStats        `json:"indexBuilds"`
}

DBStats is a point-in-time, allocation-bounded view of database health. Counters are process-lifetime values and reset when the database is reopened. Persistent state such as CommitSequence is read from the database itself.

Stats deliberately exposes no user values, document IDs, query parameters, or callbacks. It is safe for an admin sampler to call periodically, but it is not intended to be called on every database operation.

type DatabaseOptions 

type DatabaseOptions struct{ ResourceLimits ResourceLimits }

DatabaseOptions configures an in-memory database.

type DeleteResult 

type DeleteResult struct{ DeletedCount int64 }

type DiagnosticEvent 

type DiagnosticEvent struct {
	Sequence              uint64            `json:"sequence"`
	CapturedAt            time.Time         `json:"capturedAt"`
	Kind                  DiagnosticKind    `json:"kind"`
	Outcome               DiagnosticOutcome `json:"outcome"`
	ErrorClass            string            `json:"errorClass,omitempty"`
	Stage                 string            `json:"stage,omitempty"`
	PlanReason            string            `json:"planReason,omitempty"`
	FallbackReason        string            `json:"fallbackReason,omitempty"`
	EarlyStopReason       string            `json:"earlyStopReason,omitempty"`
	EarlyStopScope        string            `json:"earlyStopScope,omitempty"`
	BudgetPressure        string            `json:"budgetPressure,omitempty"`
	BudgetExceeded        string            `json:"budgetExceeded,omitempty"`
	Duration              time.Duration     `json:"durationNanos"`
	DocumentsExamined     uint64            `json:"documentsExamined,omitempty"`
	DocumentsReturned     uint64            `json:"documentsReturned,omitempty"`
	KeysExamined          uint64            `json:"keysExamined,omitempty"`
	PredicateSteps        uint64            `json:"predicateSteps,omitempty"`
	CandidateIDs          uint64            `json:"candidateIds,omitempty"`
	UniqueCandidateIDs    uint64            `json:"uniqueCandidateIds,omitempty"`
	DuplicateCandidateIDs uint64            `json:"duplicateCandidateIds,omitempty"`
	CandidatesRetained    uint64            `json:"candidatesRetained,omitempty"`
	SortBytes             uint64            `json:"sortBytes,omitempty"`
	EarlyStopped          bool              `json:"earlyStopped,omitempty"`
	Changes               uint64            `json:"changes,omitempty"`
	Slow                  bool              `json:"slow"`
	Sampled               bool              `json:"sampled"`
}

type DiagnosticKind 

type DiagnosticKind string
const (
	DiagnosticQuery  DiagnosticKind = "query"
	DiagnosticCommit DiagnosticKind = "commit"
)

type DiagnosticOutcome 

type DiagnosticOutcome string
const (
	DiagnosticSuccess  DiagnosticOutcome = "success"
	DiagnosticFailure  DiagnosticOutcome = "failure"
	DiagnosticCanceled DiagnosticOutcome = "canceled"
)

type DiagnosticSnapshot 

type DiagnosticSnapshot struct {
	Session    uint64            `json:"session"`
	StartedAt  time.Time         `json:"startedAt"`
	CapturedAt time.Time         `json:"capturedAt"`
	Stats      DiagnosticStats   `json:"stats"`
	Events     []DiagnosticEvent `json:"events"`
	Truncated  bool              `json:"truncated"`
	HasMore    bool              `json:"hasMore"`
}

type DiagnosticStats 

type DiagnosticStats struct {
	Enabled         bool   `json:"enabled"`
	Capacity        uint64 `json:"capacity"`
	Retained        uint64 `json:"retained"`
	Recorded        uint64 `json:"recorded"`
	Overwritten     uint64 `json:"overwritten"`
	QueriesObserved uint64 `json:"queriesObserved"`
	CommitsObserved uint64 `json:"commitsObserved"`
}

type Diagnostics 

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

Diagnostics owns a fixed-capacity event ring. Close disables future timing and recording but keeps the retained snapshot readable by its owner.

func (*Diagnostics) Close 

func (d *Diagnostics) Close() error

func (*Diagnostics) DiagnosticSnapshotAfter 

func (d *Diagnostics) DiagnosticSnapshotAfter(after uint64, limit int) DiagnosticSnapshot

DiagnosticSnapshotAfter lets a fixed Diagnostics handle also satisfy admin diagnostic-source contracts.

func (*Diagnostics) Snapshot 

func (d *Diagnostics) Snapshot() DiagnosticSnapshot

func (*Diagnostics) SnapshotAfter 

func (d *Diagnostics) SnapshotAfter(after uint64, limit int) DiagnosticSnapshot

SnapshotAfter returns retained events with sequence greater than after in chronological order. A non-positive limit means the ring capacity. Truncated reports that after predates the oldest retained sequence; HasMore asks the caller to continue from the last returned sequence.

func (*Diagnostics) Stats 

func (d *Diagnostics) Stats() DiagnosticStats

type DiagnosticsOptions 

type DiagnosticsOptions struct {
	Capacity            int
	SlowQueryThreshold  time.Duration
	SlowCommitThreshold time.Duration
	SampleEvery         uint64
	RecordAll           bool
	ExcludeFailures     bool
}

DiagnosticsOptions controls opt-in detailed events. Defaults retain 256 events and record failed, >=50ms queries and >=100ms durable commits. Setting RecordAll is intended only for short development sessions. SampleEvery adds a deterministic one-in-N sample of otherwise fast successful operations.

type Document 

type Document map[string]Value

func NewDocument 

func NewDocument(fields map[string]any) (Document, error)

func UnmarshalWireDocument 

func UnmarshalWireDocument(data []byte, limits QueryLimits) (Document, error)

func UnmarshalWireInputDocument 

func UnmarshalWireInputDocument(data []byte, limits QueryLimits) (Document, error)

func (Document) Clone 

func (d Document) Clone() Document

func (Document) Equal 

func (d Document) Equal(other Document) bool

func (Document) ID 

func (d Document) ID() (DocumentID, bool)

func (Document) Validate 

func (d Document) Validate() error

Validate checks every nested field and value before a document crosses a storage or transport boundary.

type DocumentCacheStats 

type DocumentCacheStats struct {
	CapacityEntries uint64 `json:"capacityEntries"`
	CapacityBytes   uint64 `json:"capacityBytes"`
	Entries         uint64 `json:"entries"`
	Bytes           uint64 `json:"bytes"`
	Hits            uint64 `json:"hits"`
	Misses          uint64 `json:"misses"`
	Evictions       uint64 `json:"evictions"`
}

type DocumentID 

type DocumentID [16]byte

func NewDocumentID 

func NewDocumentID() (DocumentID, error)

func ParseDocumentID 

func ParseDocumentID(s string) (DocumentID, error)

func (DocumentID) IsZero 

func (id DocumentID) IsZero() bool

func (DocumentID) String 

func (id DocumentID) String() string

type DurabilityStats 

type DurabilityStats struct {
	WALAppends           uint64        `json:"walAppends"`
	WALPayloadBytes      uint64        `json:"walPayloadBytes"`
	WALCurrentBytes      uint64        `json:"walCurrentBytes"`
	WALCurrentCommits    uint64        `json:"walCurrentCommits"`
	WALAppendFailures    uint64        `json:"walAppendFailures"`
	WALAppendNanos       uint64        `json:"walAppendNanos"`
	WALAppendMaxLatency  time.Duration `json:"walAppendMaxLatencyNanos"`
	CheckpointAttempts   uint64        `json:"checkpointAttempts"`
	CheckpointsCompleted uint64        `json:"checkpointsCompleted"`
	CheckpointFailures   uint64        `json:"checkpointFailures"`
	AutomaticCheckpoints uint64        `json:"automaticCheckpoints"`
	CheckpointNanos      uint64        `json:"checkpointNanos"`
	CheckpointMaxLatency time.Duration `json:"checkpointMaxLatencyNanos"`
}

DurabilityStats is retained in the admin wire contract. Current-format databases do not use a WAL or checkpoints, so every field is zero.

type DurableChangeBatch 

type DurableChangeBatch struct {
	Token   uint64
	Changes []Change
}

DurableChangeBatch is one globally ordered Commit Log position projected to one collection. Changes is empty when another collection or private catalog change advanced the durable position; callers must still Ack that Token after processing it so the checkpoint can advance without pinning history forever.

This is deliberately a document-change feed, not a full replication protocol: it does not expose private System records, index definitions, collection lifecycle or raw storage bytes.

type DurableChangeSubscription 

type DurableChangeSubscription struct {
	Batches <-chan DurableChangeBatch
	Errors  <-chan error
	// contains filtered or unexported fields
}

DurableChangeSubscription is a pull/acknowledge bridge over a durable checkpoint. Batches remain ordered. Ack must be called only after the consumer's external side effect for that token is durable.

func (*DurableChangeSubscription) Ack 

func (subscription *DurableChangeSubscription) Ack(token uint64) error

func (*DurableChangeSubscription) Close 

func (subscription *DurableChangeSubscription) Close()

type DurableDatabaseChangeBatch 

type DurableDatabaseChangeBatch struct {
	Token         uint64
	TransactionID [16]byte
	CommittedAt   time.Time
	Changes       []Change
}

DurableDatabaseChangeBatch is one globally ordered Commit Log position projected into public document and catalog events. It is the semantic source for archive and single-writer-follower protocols: callers must Ack only after the externally applied effect for Token is durable.

Private System records, raw pages, index-build progress and retention control records are deliberately excluded. A batch can therefore be empty when a private record advanced a retained position; it must still be Acked.

type DurableDatabaseChangeSubscription 

type DurableDatabaseChangeSubscription struct {
	Batches <-chan DurableDatabaseChangeBatch
	Errors  <-chan error
	// contains filtered or unexported fields
}

DurableDatabaseChangeSubscription is a crash-resumable pull/acknowledge feed over the complete public database. It exposes collection creation, index publication and document changes in exact Commit Log order. It does not itself copy a bootstrap snapshot or apply changes to a follower; those transport and ownership contracts are intentionally separate.

func (*DurableDatabaseChangeSubscription) Ack 

func (subscription *DurableDatabaseChangeSubscription) Ack(token uint64) error

func (*DurableDatabaseChangeSubscription) Checkpoint 

func (subscription *DurableDatabaseChangeSubscription) Checkpoint() (uint64, error)

Checkpoint returns the consumer's last durable acknowledgement. Delivered batches do not move it; callers may use it to bind a replication hello to the exact retained position, rather than to a process-local queue position.

func (*DurableDatabaseChangeSubscription) Close 

func (subscription *DurableDatabaseChangeSubscription) Close()

type ExplainAccessSource 

type ExplainAccessSource struct {
	IndexName                                 string
	Primary                                   bool
	Bounds                                    []ExplainBound
	Spans, ExactSpans                         int
	KeysExamined, CandidateIDs                int64
	UniqueCandidateIDs, DuplicateCandidateIDs int64
	DocumentsExamined                         int64
}

ExplainAccessSource reports the physical work attributed to one primary or secondary access path. CandidateIDs counts document IDs processed by the deduplicator. Read-ahead needed for an ordered union remains visible in KeysExamined even when execution stops before those IDs are consumed.

type ExplainAdvice 

type ExplainAdvice struct {
	Code  string
	Paths []string
	Sort  []SortField
}

ExplainAdvice is a conservative, structured observation rather than an instruction to create an index. Paths and Sort contain schema facts but never query values. Callers should validate selectivity against workload measurements.

type ExplainBound 

type ExplainBound struct {
	Path                           string
	Values                         []Value
	Lower, Upper                   *Value
	LowerInclusive, UpperInclusive bool
}

ExplainBound describes the logical values used to constrain one selected index component. Values is used for equality and membership unions; range bounds use Lower and Upper. A nil range endpoint is unbounded.

type ExplainBudget 

type ExplainBudget struct {
	DocumentsUsed, DocumentsLimit           uint64
	KeysUsed, KeysLimit                     uint64
	CandidatesUsed, CandidatesLimit         uint64
	SortBytesUsed, SortBytesLimit           uint64
	SkipUsed, SkipLimit                     uint64
	PredicateStepsUsed, PredicateStepsLimit uint64
	Pressure, Exceeded                      string
}

ExplainBudget is the final resource-budget snapshot for one execution. Pressure and Exceeded are fixed reason codes naming one of "documents", "keys", "candidates", "sort_bytes", "skip", or "predicate_steps".

type ExplainResult 

type ExplainResult struct {
	Stage, IndexName string
	// IndexNames contains every access path used by an index union. IndexName
	// remains populated for the common single-index and primary-key plans.
	IndexNames                        []string
	Bounds                            []ExplainBound
	ResidualPredicate, SortRequired   bool
	SortIndexCompatible               bool
	EstimatedDocuments, EstimatedKeys int64
	DocumentsExamined, KeysExamined   int64
	CandidatesRetained, SortBytes     uint64
	PlanReason, FallbackReason        string
	UnindexedPaths                    []string
	// IndexableConjunctPaths lists distinct AND predicate paths that each have
	// an independently usable access path. It is populated only by explicit
	// Explain calls and does not imply that an index intersection was selected.
	IndexableConjunctPaths []string
	// CompoundIndexOpportunity is a structural signal: multiple independently
	// indexable AND paths exist, while the selected non-unique source constrains
	// only a subset. Advice still requires observed amplification.
	CompoundIndexOpportunity         bool
	Sources                          []ExplainAccessSource
	CandidateIDs, UniqueCandidateIDs int64
	DuplicateCandidateIDs            int64
	EarlyStopEligible, EarlyStopped  bool
	EarlyStopScope, EarlyStopReason  string
	Budget                           ExplainBudget
	Advice                           []ExplainAdvice
}

ExplainResult separates plan facts from observed work. Estimated fields are conservative candidate estimates when the selected backend can provide them; DocumentsExamined and KeysExamined are the actual completed scan counts. ResidualPredicate means the complete compiled predicate is rechecked after index admission, including when the index appears to cover every condition.

type Filter 

type Filter map[string]any

type FilterCapability 

type FilterCapability struct {
	Path     string
	Operator string
}

FilterCapability identifies one field-level predicate operation used by a compiled query. It is exposed separately from sort and result paths so authorization can grant equality lookup without granting range scans.

type Follower 

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

Follower owns a local, read-only database that advances only through validated DurableDatabaseChangeBatch values. It is the local application half of a future remote replication protocol; transport authentication, snapshot transfer and promotion deliberately remain outside this type.

func OpenFollower 

func OpenFollower(path string, options OpenOptions) (*Follower, error)

OpenFollower opens a physical archive/bootstrap copy as a replica. Normal public mutations on DB return ErrReplicaReadOnly; use Apply to advance the next source token. The returned DB remains fully queryable and reactive.

func (*Follower) Apply 

func (follower *Follower) Apply(ctx context.Context, source DurableDatabaseChangeBatch) error

Apply durably and atomically applies exactly the next source batch. A gap, duplicate or locally diverged token returns ErrReplicaSequence; it never guesses, retries business logic or advances past missing history.

func (*Follower) ApplyFrame 

func (follower *Follower) ApplyFrame(ctx context.Context, frame ReplicationFrame) error

ApplyFrame binds the decoded transport envelope to this bootstrap's durable identity before applying its batch. A transport handles hello/ack/resync; only a validated batch frame belongs at the follower mutation boundary.

func (*Follower) Close 

func (follower *Follower) Close() error

func (*Follower) DB 

func (follower *Follower) DB() *DB

func (*Follower) Promote 

func (follower *Follower) Promote(ctx context.Context, authority FollowerPromotionAuthority) (FollowerPromotionFence, error)

Promote makes this follower writable only after an external authority fences the former primary at this exact identity/token. There is intentionally no default or best-effort implementation: promoting without a durable external fence would turn a network partition into split-brain data loss.

type FollowerPromotionAuthority 

type FollowerPromotionAuthority interface {
	AuthorizeFollowerPromotion(context.Context, FollowerPromotionRequest) (FollowerPromotionFence, error)
}

FollowerPromotionAuthority must make its returned fence durable before it returns. Implementations normally revoke a primary lease through a quorum controller or external consensus store.

type FollowerPromotionFence 

type FollowerPromotionFence struct {
	DatabaseID     [16]byte
	CommitSequence uint64
	Epoch          string
}

FollowerPromotionFence is a controller-issued, non-empty epoch proving the old primary's write authority was fenced for this database/token. Epoch is deliberately opaque to Meldbase: a controller may use it as an epoch ID or a compact signed lease certificate (as integrations/primarylease does). Meldbase does not invent a local substitute for that distributed safety decision.

type FollowerPromotionFenceBinder 

type FollowerPromotionFenceBinder interface {
	BindFollowerPromotion(context.Context, FollowerPromotionFence) error
}

FollowerPromotionFenceBinder binds one controller-issued promotion fence to the local primary-write guard before a follower becomes writable. The binder may update caller-owned local lease/epoch state, but must not enable writes until it has accepted the exact fence. It runs on the promotion control path, outside the DB writer lock; unlike ValidatePrimaryWrite it may coordinate with the controller if the implementation needs to.

A promoted follower requires this interface in addition to PrimaryWriteFence. Otherwise an unrelated always-allow guard could make a one-time promotion certificate appear to grant permanent write authority.

type FollowerPromotionRequest 

type FollowerPromotionRequest struct {
	DatabaseID     [16]byte
	CommitSequence uint64
}

FollowerPromotionRequest is the exact local state an external fencing system must certify before this process can become writable primary.

type IndexBuildFailure 

type IndexBuildFailure string

type IndexBuildID 

type IndexBuildID [16]byte

IndexBuildID identifies one durable, resumable Storage index build.

func ParseIndexBuildID 

func ParseIndexBuildID(value string) (IndexBuildID, error)

func (IndexBuildID) IsZero 

func (id IndexBuildID) IsZero() bool

func (IndexBuildID) MarshalText 

func (id IndexBuildID) MarshalText() ([]byte, error)

func (IndexBuildID) String 

func (id IndexBuildID) String() string

func (*IndexBuildID) UnmarshalText 

func (id *IndexBuildID) UnmarshalText(value []byte) error

type IndexBuildPhase 

type IndexBuildPhase string

type IndexBuildScheduler 

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

func (*IndexBuildScheduler) Done 

func (scheduler *IndexBuildScheduler) Done() <-chan struct{}

func (*IndexBuildScheduler) Stats 

func (scheduler *IndexBuildScheduler) Stats() IndexBuildSchedulerStats

func (*IndexBuildScheduler) Stop 

func (scheduler *IndexBuildScheduler) Stop()

type IndexBuildSchedulerOptions 

type IndexBuildSchedulerOptions struct {
	PollInterval   time.Duration
	RunTimeout     time.Duration
	MaxConcurrency int
	RunImmediately bool
}

IndexBuildSchedulerOptions configures an explicit default-off runner. Each task receives a bounded time quantum, then yields durable progress so CRUD and other builds can proceed between quanta.

type IndexBuildSchedulerStats 

type IndexBuildSchedulerStats struct {
	Polls        uint64        `json:"polls"`
	Runs         uint64        `json:"runs"`
	Completed    uint64        `json:"completed"`
	Yielded      uint64        `json:"yielded"`
	MarkedFailed uint64        `json:"markedFailed"`
	Conflicts    uint64        `json:"conflicts"`
	Failed       uint64        `json:"failed"`
	Active       uint64        `json:"active"`
	LastDuration time.Duration `json:"lastDurationNanos"`
	LastError    string        `json:"lastError,omitempty"`
}

type IndexBuildStats 

type IndexBuildStats struct {
	Active               uint64        `json:"active"`
	Persistent           uint64        `json:"persistent"`
	Scanning             uint64        `json:"scanning"`
	CatchingUp           uint64        `json:"catchingUp"`
	Ready                uint64        `json:"ready"`
	PersistentFailed     uint64        `json:"persistentFailed"`
	RetentionLeaseActive bool          `json:"retentionLeaseActive"`
	RetentionPressure    bool          `json:"retentionPressure"`
	PersistentEntries    uint64        `json:"persistentEntries"`
	PersistentBytes      uint64        `json:"persistentBytes"`
	SchedulerRuns        uint64        `json:"schedulerRuns"`
	SchedulerYields      uint64        `json:"schedulerYields"`
	SchedulerFailures    uint64        `json:"schedulerFailures"`
	Attempts             uint64        `json:"attempts"`
	Completed            uint64        `json:"completed"`
	Failed               uint64        `json:"failed"`
	Retries              uint64        `json:"retries"`
	Conflicts            uint64        `json:"conflicts"`
	LastEntries          uint64        `json:"lastEntries"`
	LastBytes            uint64        `json:"lastBytes"`
	LastDuration         time.Duration `json:"lastDurationNanos"`
	MaxDuration          time.Duration `json:"maxDurationNanos"`
	// contains filtered or unexported fields
}

type IndexBuildStatus 

type IndexBuildStatus struct {
	ID              IndexBuildID      `json:"id"`
	Collection      string            `json:"collection"`
	Name            string            `json:"name"`
	Field           string            `json:"field"`
	Fields          []IndexField      `json:"fields"`
	Unique          bool              `json:"unique"`
	ReplaceExisting bool              `json:"replaceExisting,omitempty"`
	Phase           IndexBuildPhase   `json:"phase"`
	Failure         IndexBuildFailure `json:"failure,omitempty"`
	SourceSequence  uint64            `json:"sourceSequence"`
	AppliedSequence uint64            `json:"appliedSequence"`
	EntryCount      uint64            `json:"entryCount"`
	CanonicalBytes  uint64            `json:"canonicalBytes"`
	CreatedAt       time.Time         `json:"createdAt"`
	UpdatedAt       time.Time         `json:"updatedAt"`
}

IndexBuildStatus is durable progress. EntryCount and CanonicalBytes describe the current private Secondary tree, not transient Go heap usage.

type IndexCatalogEntry 

type IndexCatalogEntry struct {
	Collection string
	Definition IndexDefinition
}

IndexCatalogEntry is an immutable operator-facing description of one published index. It contains no document keys, values, or cardinalities. Index management remains a deployment concern; this is intentionally a read-only catalog for CLIs and protected operator surfaces.

type IndexDefinition 

type IndexDefinition struct {
	Name, Field string
	Order       int
	Unique      bool
	// Fields is the ordered definition for compound/descending indexes. Field
	// and Order remain the compatibility mirror of Fields[0] for existing
	// callers; new code must use indexDefinitionFields.
	Fields []IndexField
}

type IndexField 

type IndexField struct {
	Field string
	Order int
}

IndexField is one ordered component of an index definition. Order must be 1 (ascending) or -1 (descending); fields are evaluated left to right.

type IndexOptions 

type IndexOptions struct{ Unique bool }

IndexOptions controls complete-tuple uniqueness.

type Kind 

type Kind uint8
const (
	NullKind Kind = iota
	BoolKind
	Int64Kind
	Float64Kind
	StringKind
	BinaryKind
	TimeKind
	ArrayKind
	ObjectKind
	IDKind
)

type LogicalArchiveImportOptions 

type LogicalArchiveImportOptions struct{ MaxBytes uint64 }

LogicalArchiveImportOptions bounds an untrusted logical archive. Zero MaxBytes selects the normal storage-file limit; the receiver owns this cap.

type LogicalArchiveResult 

type LogicalArchiveResult struct {
	Format      string `json:"format"`
	Version     int    `json:"version"`
	Bytes       uint64 `json:"bytes"`
	Collections uint64 `json:"collections"`
	Documents   uint64 `json:"documents"`
	Indexes     uint64 `json:"indexes"`
	SHA256      string `json:"sha256"`
}

LogicalArchiveResult is the portable, data-only archive receipt. SHA256 covers every JSONL record before the final end record; the end record stores the same digest so an importer can reject truncation or alteration.

func ImportLogicalArchive 

func ImportLogicalArchive(ctx context.Context, source io.Reader, destination string, options LogicalArchiveImportOptions) (result LogicalArchiveResult, resultErr error)

ImportLogicalArchive validates and applies a portable archive into a private temporary database, verifies that database offline, then atomically publishes it at destination. A malformed archive never leaves a destination database.

type Maintenance 

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

Maintenance owns one background reclamation loop. Stop is idempotent and waits for an active scan to observe cancellation. Closing the DB also stops the loop through the DB lifecycle channel.

func (*Maintenance) Done 

func (maintenance *Maintenance) Done() <-chan struct{}

func (*Maintenance) Stats 

func (maintenance *Maintenance) Stats() MaintenanceStats

func (*Maintenance) Stop 

func (maintenance *Maintenance) Stop()

type MaintenanceOptions 

type MaintenanceOptions struct {
	Interval       time.Duration
	Timeout        time.Duration
	MaxAttempts    int
	RunImmediately bool
	// PersistFreeSpace opts into a physical maintenance generation after each
	// successful scan. The default memory-only mode minimizes writer pauses.
	PersistFreeSpace bool
}

MaintenanceOptions configures an explicit default-off maintenance loop. Every run uses online optimistic reclamation; runs never overlap.

type MaintenanceStats 

type MaintenanceStats struct {
	Runs         uint64
	Completed    uint64
	Conflicts    uint64
	Failed       uint64
	Active       bool
	LastDuration time.Duration
	LastError    string
}

type MutationSpec 

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

func CompileUpdate 

func CompileUpdate(update Update) (MutationSpec, error)

func DecodeMutationSpecJSON 

func DecodeMutationSpecJSON(data []byte, limits QueryLimits) (MutationSpec, error)

func (MutationSpec) Apply 

func (m MutationSpec) Apply(document Document) (Document, error)

func (MutationSpec) Paths 

func (m MutationSpec) Paths() []string

type OpenOptions 

type OpenOptions struct {
	Recovery              RecoveryMode
	CommitRetention       CommitRetentionPolicy
	ReplayDeliveryTimeout time.Duration
	CommitCoordinator     CommitCoordinatorOptions
	ResourceLimits        ResourceLimits
	StorageLimits         StorageLimits
	RollbackProtection    RollbackProtection
	// RequireGraphAudit rejects a database at startup when any page
	// protected by the current or fallback Meta root is structurally invalid.
	// It is intentionally opt-in because audit cost grows with database size.
	// This does not replace the offline semantic index verifier.
	RequireGraphAudit bool
	// RequirePrivateFileMode rejects a database file with group/world permission
	// bits instead of silently changing operator-owned permissions.
	RequirePrivateFileMode bool
	// PrimaryWriteFence optionally proves that this local database still holds
	// external primary authority before every business commit. It is not
	// consulted by a read-only follower applying an already validated source
	// batch. The guard must be local, non-blocking and safe for concurrent use;
	// controller I/O/lease renewal belongs outside Meldbase's writer lock.
	PrimaryWriteFence PrimaryWriteFence
	// Follower marks this local open as a replica. Normal application writes
	// fail with ErrReplicaReadOnly; only Follower.Apply may advance it.
	Follower bool
}

OpenOptions configures the current durable storage format.

type Operation 

type Operation string
const (
	InsertOperation Operation = "insert"
	UpdateOperation Operation = "update"
	DeleteOperation Operation = "delete"
	// CreateCollectionOperation is emitted only by the durable database change
	// feed. Ordinary collection creation remains implicit for CRUD callers.
	CreateCollectionOperation Operation = "create_collection"
	CreateIndexOperation      Operation = "create_index"
	ReplaceIndexOperation     Operation = "replace_index"
)

type OperationalState 

type OperationalState struct {
	Readable bool `json:"readable"`
	Writable bool `json:"writable"`
}

OperationalState is a minimal, allocation-free serving-state snapshot. A fail-stop durability error preserves reads from the last committed state but disables writes; a closed database is neither readable nor writable.

type PageCacheStats 

type PageCacheStats struct {
	CapacityPages uint64 `json:"capacityPages"`
	ResidentPages uint64 `json:"residentPages"`
	Hits          uint64 `json:"hits"`
	Misses        uint64 `json:"misses"`
	Evictions     uint64 `json:"evictions"`
}

type PhysicalBackupImportOptions 

type PhysicalBackupImportOptions struct {
	MaxBytes uint64
}

PhysicalBackupImportOptions bounds an untrusted physical-backup stream before it can consume local disk. Zero selects the normal file limit. Deployments with a deliberately larger database must set MaxBytes explicitly on the receiving side; a sender never chooses that authority.

type PrimaryWriteFence 

type PrimaryWriteFence interface {
	ValidatePrimaryWrite(PrimaryWriteFenceRequest) error
}

PrimaryWriteFence is the local enforcement hook for an external primary election/fencing system. Its implementation normally checks an atomically refreshed lease epoch and expiry, not the network. Returning an error rejects the whole logical commit before storage mutation; it never poisons the database or advances a token.

Implementations must not call back into DB and must return promptly: the check runs while the writer has admitted a commit. Election, renewal, certificate rotation and old-primary revocation remain external concerns.

type PrimaryWriteFenceRequest 

type PrimaryWriteFenceRequest struct {
	DatabaseID         [16]byte
	NextCommitSequence uint64
}

PrimaryWriteFenceRequest binds a proposed primary mutation to this database identity and exact next logical commit sequence. A lease implementation must reject when its external authority/epoch/expiry no longer permits that write.

type PrimaryWriteFenceStats 

type PrimaryWriteFenceStats struct {
	Configured bool   `json:"configured"`
	Enforced   bool   `json:"enforced"`
	Checks     uint64 `json:"checks"`
	Rejected   uint64 `json:"rejected"`
}

PrimaryWriteFenceStats is a fixed-cardinality view of the optional external primary-write guard. Configured means a guard was supplied at open; Enforced is false while a read-only follower applies validated source history. Checks and Rejected count only actual primary write admissions. No lease, epoch, endpoint, database ID, or controller detail is exposed.

type QueryDelta 

type QueryDelta struct {
	FromToken  uint64
	Token      uint64
	Operations []QueryDeltaOperation
}

QueryDelta transforms exactly FromToken into Token. Operations are ordered: removals first, followed by reverse-order add/move anchors and document changes. Applying them in slice order is deterministic.

type QueryDeltaOperation 

type QueryDeltaOperation struct {
	Kind       QueryDeltaOperationKind
	DocumentID DocumentID
	BeforeID   DocumentID
	Document   Document
}

QueryDeltaOperation mutates an ordered query result. A zero BeforeID means the end of the result; database document IDs are never zero.

type QueryDeltaOperationKind 

type QueryDeltaOperationKind string
const (
	QueryDeltaRemove QueryDeltaOperationKind = "remove"
	QueryDeltaAdd    QueryDeltaOperationKind = "add_before"
	QueryDeltaMove   QueryDeltaOperationKind = "move_before"
	QueryDeltaChange QueryDeltaOperationKind = "change"
)

type QueryDeltaSubscription 

type QueryDeltaSubscription struct {
	Initial QuerySnapshot
	Deltas  <-chan QueryDelta
	Errors  <-chan error
	// contains filtered or unexported fields
}

QueryDeltaSubscription returns one safe initial snapshot and then ordered deltas. It is the preferred core stream for transports and reactive clients; QuerySubscription remains the full-snapshot compatibility adapter.

func (*QueryDeltaSubscription) Close 

func (s *QueryDeltaSubscription) Close()

type QueryLimits 

type QueryLimits struct {
	MaxWireBytes  int
	MaxDepth      int
	MaxNodes      int
	MaxArrayItems int
	MaxValueBytes int
	MaxSortFields int
	MaxLimit      int
}

type QueryOptions 

type QueryOptions struct {
	Sort  []SortField
	Skip  int
	Limit *int
}

type QueryReplaySource 

type QueryReplaySource interface {
	OpenQueryReplay(ctx context.Context, collection string, query QuerySpec, afterToken uint64, buffer int) (*QueryReplaySubscription, error)
}

QueryReplaySource atomically reconstructs a query at afterToken and tails later ordered revisions. Initial.Token must equal afterToken. Implementations return ErrHistoryLost when retention can no longer satisfy that contract.

type QueryReplaySubscription 

type QueryReplaySubscription struct {
	Initial QuerySnapshot
	Deltas  <-chan QueryDelta
	Errors  <-chan error
	// contains filtered or unexported fields
}

func (*QueryReplaySubscription) Close 

func (subscription *QueryReplaySubscription) Close()

type QuerySnapshot 

type QuerySnapshot struct {
	Token     uint64
	Documents []Document
}

func ApplyQueryDelta 

func ApplyQueryDelta(snapshot QuerySnapshot, delta QueryDelta) (QuerySnapshot, error)

ApplyQueryDelta strictly validates and applies an ordered delta without mutating the input snapshot.

type QuerySpec 

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

func CompileQuery 

func CompileQuery(filter Filter, options QueryOptions) (QuerySpec, error)

func DecodeQuerySpecJSON 

func DecodeQuerySpecJSON(data []byte, limits QueryLimits) (QuerySpec, error)

func (QuerySpec) Capped 

func (q QuerySpec) Capped(max int) QuerySpec

func (QuerySpec) Constrain 

func (q QuerySpec) Constrain(policy QuerySpec) QuerySpec

Constrain applies a server-owned row predicate before the caller's sort and pagination. This is the safe composition point for authorization policies.

func (QuerySpec) Execute 

func (q QuerySpec) Execute(documents []Document) []Document

func (QuerySpec) FilterCapabilities 

func (q QuerySpec) FilterCapabilities() []FilterCapability

func (QuerySpec) HasModifiers 

func (q QuerySpec) HasModifiers() bool

func (QuerySpec) Limit 

func (q QuerySpec) Limit() (int, bool)

func (QuerySpec) Match 

func (q QuerySpec) Match(document Document) bool

func (QuerySpec) Paths 

func (q QuerySpec) Paths() []string

func (QuerySpec) Skip 

func (q QuerySpec) Skip() int

func (QuerySpec) Sort 

func (q QuerySpec) Sort() []SortField

func (QuerySpec) SortPaths 

func (q QuerySpec) SortPaths() []string

func (QuerySpec) UsesSeekPagination 

func (q QuerySpec) UsesSeekPagination() bool

func (QuerySpec) Validate 

func (q QuerySpec) Validate() error

Validate verifies that a compiled query can safely enter any public query execution API. QuerySpec intentionally has private fields, but its zero value is still constructible by callers and must never reach a nil expression.

type QueryStats 

type QueryStats struct {
	ActiveCursors         uint64 `json:"activeCursors"`
	Total                 uint64 `json:"total"`
	Failed                uint64 `json:"failed"`
	CollectionScans       uint64 `json:"collectionScans"`
	IndexScans            uint64 `json:"indexScans"`
	IDLookups             uint64 `json:"idLookups"`
	DocumentsExamined     uint64 `json:"documentsExamined"`
	DocumentsReturned     uint64 `json:"documentsReturned"`
	KeysExamined          uint64 `json:"keysExamined"`
	PredicateSteps        uint64 `json:"predicateSteps"`
	CandidateIDs          uint64 `json:"candidateIds"`
	UniqueCandidateIDs    uint64 `json:"uniqueCandidateIds"`
	DuplicateCandidateIDs uint64 `json:"duplicateCandidateIds"`
	CandidatesRetained    uint64 `json:"candidatesRetained"`
	SortBytes             uint64 `json:"sortBytes"`
	EarlyStops            uint64 `json:"earlyStops"`
	BudgetPressureEvents  uint64 `json:"budgetPressureEvents"`
	BudgetRejections      uint64 `json:"budgetRejections"`
}

QueryStats contains fixed-cardinality process-session counters. Physical key and candidate counters include work completed before a failed query; the older document/return counters retain their successful-query contract.

type QuerySubscription 

type QuerySubscription struct {
	Snapshots <-chan QuerySnapshot
	Errors    <-chan error
	// contains filtered or unexported fields
}

func (*QuerySubscription) Close 

func (s *QuerySubscription) Close()

type RealtimeStats 

type RealtimeStats struct {
	SharedViews            uint64 `json:"sharedViews"`
	QuerySubscribers       uint64 `json:"querySubscribers"`
	SharedViewReuses       uint64 `json:"sharedViewReuses"`
	IncrementalBatches     uint64 `json:"incrementalBatches"`
	IncrementalViewUpdates uint64 `json:"incrementalViewUpdates"`
	FullViewRecomputes     uint64 `json:"fullViewRecomputes"`
	QueueOverflows         uint64 `json:"queueOverflows"`
	PendingBatches         uint64 `json:"pendingBatches"`
	PendingChanges         uint64 `json:"pendingChanges"`
	PendingBytes           uint64 `json:"pendingBytes"`
	PendingBatchCapacity   uint64 `json:"pendingBatchCapacity"`
	PendingChangeCapacity  uint64 `json:"pendingChangeCapacity"`
	PendingByteCapacity    uint64 `json:"pendingByteCapacity"`
	WatcherPendingBytes    uint64 `json:"watcherPendingBytes"`
	WatcherByteCapacity    uint64 `json:"watcherByteCapacity"`
	DispatchPendingBatches uint64 `json:"dispatchPendingBatches"`
	DispatchPendingChanges uint64 `json:"dispatchPendingChanges"`
	DispatchPendingBytes   uint64 `json:"dispatchPendingBytes"`
	DispatchBatchCapacity  uint64 `json:"dispatchBatchCapacity"`
	DispatchChangeCapacity uint64 `json:"dispatchChangeCapacity"`
	DispatchByteCapacity   uint64 `json:"dispatchByteCapacity"`
	SharedDeltas           uint64 `json:"sharedDeltas"`
	DeltaDeliveries        uint64 `json:"deltaDeliveries"`
	DeltaOperations        uint64 `json:"deltaOperations"`
	PublishedBatches       uint64 `json:"publishedBatches"`
	PublishedChanges       uint64 `json:"publishedChanges"`
	WatcherDeliveries      uint64 `json:"watcherDeliveries"`
	InitialSnapshots       uint64 `json:"initialSnapshots"`
	QueryRecomputes        uint64 `json:"queryRecomputes"`
	SnapshotsEmitted       uint64 `json:"snapshotsEmitted"`
	DocumentsEmitted       uint64 `json:"documentsEmitted"`
	SlowConsumers          uint64 `json:"slowConsumers"`
}

type ReclaimOptions 

type ReclaimOptions struct {
	Online      bool
	MaxAttempts int
	// MemoryOnly skips the physical FreeSpace maintenance generation. It keeps
	// the final installation pause O(1), but another audit is needed after reopen.
	MemoryOnly bool
}

ReclaimOptions controls explicit page reclamation. Online scans a duplicate read handle without holding the storage writer lock and installs its result only if the Meta generation is unchanged. MaxAttempts bounds complete graph rescans after concurrent commits; zero selects three attempts.

type ReclaimResult 

type ReclaimResult struct {
	PhysicalPages   uint64
	ReachablePages  uint64
	ReusablePages   uint64
	PinnedSnapshots uint64
	Attempts        int
	Online          bool
	Persisted       bool
}

type ReclamationStats 

type ReclamationStats struct {
	Active          uint64        `json:"active"`
	Attempts        uint64        `json:"attempts"`
	Scans           uint64        `json:"scans"`
	Conflicts       uint64        `json:"conflicts"`
	Completed       uint64        `json:"completed"`
	Failed          uint64        `json:"failed"`
	LastAttempts    uint64        `json:"lastAttempts"`
	LastOnline      bool          `json:"lastOnline"`
	LastReachable   uint64        `json:"lastReachable"`
	LastReclaimable uint64        `json:"lastReclaimable"`
	LastDuration    time.Duration `json:"lastDurationNanos"`
}

type RecoveryMode 

type RecoveryMode uint8

RecoveryMode controls whether Open may perform only the bounded recovery actions described by RecoveryReport. Zero selects the normal automatic mode. 

const (
	RecoveryAutomatic RecoveryMode = iota
	RecoveryRequireClean
)

type RecoveryReport 

type RecoveryReport struct {
	SchemaVersion          int    `json:"schemaVersion"`
	Engine                 string `json:"engine"`
	Created                bool   `json:"created"`
	Recovered              bool   `json:"recovered"`
	CommitSequenceBefore   uint64 `json:"commitSequenceBefore"`
	CommitSequenceAfter    uint64 `json:"commitSequenceAfter"`
	SelectedMetaSlot       uint8  `json:"selectedMetaSlot"`
	ChecksumValidMetaSlots uint8  `json:"checksumValidMetaSlots"`
	RootValidMetaSlots     uint8  `json:"rootValidMetaSlots"`
	MetaRedundancyDegraded bool   `json:"metaRedundancyDegraded"`
	FallbackToOlderRoot    bool   `json:"fallbackToOlderRoot"`
	MainTailBytesRemoved   uint64 `json:"mainTailBytesRemoved"`
	WALRecordsReplayed     uint64 `json:"walRecordsReplayed"`
	WALTailBytesRemoved    uint64 `json:"walTailBytesRemoved"`
	AccelerationDegraded   bool   `json:"accelerationDegraded"`
}

RecoveryReport is an immutable, non-sensitive receipt for decisions made while opening a database. It reports only actions that were completed before Open returned successfully; corruption and unsupported formats still fail Open instead of being described as recovered.

type ReplicationFrame 

type ReplicationFrame struct {
	Type       string
	DatabaseID [16]byte
	AfterToken uint64 // hello: receiver's durable position
	MaxBytes   int    // hello: receiver frame cap
	Batch      *DurableDatabaseChangeBatch
	AckToken   uint64
	Reason     string
}

ReplicationFrame is a transport-neutral protocol envelope. A transport must authenticate both peers (for example with mTLS) before it accepts frames; DatabaseID binds every frame to one durable source identity.

func UnmarshalReplicationFrame 

func UnmarshalReplicationFrame(data []byte, limits ReplicationFrameLimits) (ReplicationFrame, error)

UnmarshalReplicationFrame rejects unknown fields, duplicate JSON keys, malformed base64, invalid typed documents and non-canonical identities before a receiver reaches the follower state machine.

type ReplicationFrameLimits 

type ReplicationFrameLimits struct{ MaxFrameBytes int }

ReplicationFrameLimits bounds one already-decompressed protocol frame. The default accommodates the configured 64 MiB canonical transaction limit plus JSON/base64 overhead, while still rejecting unbounded peer allocation.

type ReplicationSourceLease 

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

ReplicationSourceLease gives one authenticated source-side replica identity exclusive process-local ownership of its durable consumer. A lease prevents duplicate concurrent transports from racing one checkpoint; it does not establish distributed primary authority or replace follower-promotion fencing.

func (*ReplicationSourceLease) Release 

func (lease *ReplicationSourceLease) Release()

Release is idempotent. It does not alter the durable consumer checkpoint; normal source-session ACK handling remains the only way to advance that recovery position.

type ReplicationSourceSession 

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

ReplicationSourceSession is the primary-side state machine for one authenticated peer. It deliberately permits one unacknowledged batch at a time: this is both bounded flow control and the proof that a durable ACK can never skip an unseen source token.

func NewReplicationSourceSession 

func NewReplicationSourceSession(db *DB, subscription *DurableDatabaseChangeSubscription, limits ReplicationFrameLimits) (*ReplicationSourceSession, error)

NewReplicationSourceSession binds an existing named durable database feed to one source identity. The caller owns peer authentication and must close the session when that authenticated connection ends.

func (*ReplicationSourceSession) AcceptAck 

func (session *ReplicationSourceSession) AcceptAck(frame ReplicationFrame) error

AcceptAck makes one remote acknowledgement durable on the source. The token must exactly match the one batch in flight; stale, future or duplicate ACKs cannot release retained history.

func (*ReplicationSourceSession) AcceptHello 

func (session *ReplicationSourceSession) AcceptHello(frame ReplicationFrame) (*ReplicationFrame, error)

AcceptHello validates a receiver's exact durable position. A different identity or checkpoint is a safe resync response, never an implicit rewind or jump of the source durable consumer.

func (*ReplicationSourceSession) Checkpoint 

func (session *ReplicationSourceSession) Checkpoint() (uint64, error)

func (*ReplicationSourceSession) Close 

func (session *ReplicationSourceSession) Close()

func (*ReplicationSourceSession) NextFrame 

func (session *ReplicationSourceSession) NextFrame(ctx context.Context) (*ReplicationFrame, error)

NextFrame waits for the next ordered source batch. The caller must not send another frame until AcceptAck succeeds for this token. If the peer's declared frame cap cannot carry one atomic Commit Log batch, the session terminates with snapshot_required rather than splitting or partially sending a commit.

type ResourceLimits 

type ResourceLimits struct {
	MaxDocumentBytes          uint64 `json:"maxDocumentBytes"`
	MaxTransactionBytes       uint64 `json:"maxTransactionBytes"`
	MaxTransactionChanges     uint64 `json:"maxTransactionChanges"`
	MaxIndexBuildEntries      uint64 `json:"maxIndexBuildEntries"`
	MaxIndexBuildBytes        uint64 `json:"maxIndexBuildBytes"`
	MaxReactiveViewDocuments  uint64 `json:"maxReactiveViewDocuments"`
	MaxReactiveViewBytes      uint64 `json:"maxReactiveViewBytes"`
	MaxQueryDocumentsExamined uint64 `json:"maxQueryDocumentsExamined"`
	MaxQueryKeysExamined      uint64 `json:"maxQueryKeysExamined"`
	MaxQueryCandidates        uint64 `json:"maxQueryCandidates"`
	MaxQuerySortBytes         uint64 `json:"maxQuerySortBytes"`
	MaxQuerySkip              uint64 `json:"maxQuerySkip"`
	MaxQueryPredicateSteps    uint64 `json:"maxQueryPredicateSteps"`
}

ResourceLimits bounds work admitted by writes, index maintenance, and query execution. Zero values select production defaults; limits cannot be disabled accidentally. Byte limits use the canonical typed binary representation, independent of Go heap layout, JSON spelling, storage generation, or transport compression.

type ResourceStats 

type ResourceStats struct {
	Limits     ResourceLimits `json:"limits"`
	Rejections uint64         `json:"rejections"`
}

type RollbackAnchor 

type RollbackAnchor struct {
	DatabaseID            [16]byte
	MinimumCommitSequence uint64
	MinimumGeneration     uint64
}

RollbackAnchor is trusted state retained outside the database device. A server must never accept the same identity below either an acknowledged logical commit sequence or physical maintenance generation after restart. The coordinates are independently monotonic: one group may advance several logical sequences while publishing a single physical generation.

type RollbackAnchorStatusProvider 

type RollbackAnchorStatusProvider interface {
	RollbackAnchorStatus() RollbackAnchorStoreStatus
}

RollbackAnchorStatusProvider is an optional lock-free observability contract for RollbackAnchorStore implementations.

type RollbackAnchorStore 

type RollbackAnchorStore interface {
	Load(context.Context) (RollbackAnchor, bool, error)
	Advance(context.Context, RollbackAnchor) error
}

RollbackAnchorStore durably loads and atomically advances one database's monotonic anchor. Advance must not return until the anchor is persistent and must reject identity changes or regression of either monotonic coordinate. Implementations must be safe for concurrent callers and honor cancellation. An Advance error does not prove that state was unchanged: persistence may have completed before a response, deadline or cancellation was observed.

func NewFileRollbackAnchorStore 

func NewFileRollbackAnchorStore(path string) (RollbackAnchorStore, error)

NewFileRollbackAnchorStore returns a fail-closed, atomically replaced anchor file. The parent directory must already exist. For rollback protection, that directory must be backed by storage trusted independently from the database.

type RollbackAnchorStoreStatus 

type RollbackAnchorStoreStatus struct {
	Replicas               uint64 `json:"replicas"`
	Quorum                 uint64 `json:"quorum"`
	Loads                  uint64 `json:"loads"`
	Advances               uint64 `json:"advances"`
	EndpointFailures       uint64 `json:"endpointFailures"`
	QuorumFailures         uint64 `json:"quorumFailures"`
	Conflicts              uint64 `json:"conflicts"`
	AuthenticationFailures uint64 `json:"authenticationFailures"`
	ProtocolFailures       uint64 `json:"protocolFailures"`
	ConfigurationFailures  uint64 `json:"configurationFailures"`
}

RollbackAnchorStoreStatus is a bounded, identity-free process-session view of an anchor backend. Counters are diagnostic and never participate in recovery.

type RollbackProtection 

type RollbackProtection struct {
	ExpectedDatabaseID    [16]byte
	MinimumCommitSequence uint64
	MinimumGeneration     uint64
	AnchorStore           RollbackAnchorStore
	InitializeAnchor      bool
	// OperationTimeout bounds each Load/Advance/read-back interaction. Zero
	// selects DefaultRollbackAnchorOperationTimeout.
	OperationTimeout time.Duration
}

RollbackProtection configures fail-closed database identity and sequence checks. AnchorStore should live on an independently trusted device or remote quorum; placing it beside the database cannot detect whole-device rollback. InitializeAnchor explicitly trusts the database currently at Path when the store is empty and should only be used during provisioning or audited restore.

type SortField 

type SortField struct {
	Path      string `json:"path"`
	Direction int    `json:"direction"`
}

type StorageFormat 

type StorageFormat string

StorageFormat identifies the sole supported on-disk engine. Unknown denotes a missing or zero-length path, not an unrecognized non-empty file. 

const (
	StorageFormatUnknown StorageFormat = ""
	StorageFormatCurrent StorageFormat = "current"
)

func DetectStorageFormat 

func DetectStorageFormat(path string) (StorageFormat, error)

DetectStorageFormat performs only enough inspection to distinguish a new path from the current database format. Old database files deliberately fail closed: this build contains no legacy reader or automatic migration path.

type StorageFormatInfo 

type StorageFormatInfo struct {
	Format            StorageFormat `json:"format"`
	Revision          uint16        `json:"revision"`
	Generation        uint64        `json:"generation"`
	CommitSequence    uint64        `json:"commitSequence"`
	PhysicalPageCount uint64        `json:"physicalPageCount,omitempty"`
	RequiredFeatures  uint64        `json:"requiredFeatures"`
	OptionalFeatures  uint64        `json:"optionalFeatures"`
	DatabaseIDHex     string        `json:"databaseIdHex,omitempty"`
	ValidMetaSlots    int           `json:"validMetaSlots"`
	ReaderCompatible  bool          `json:"readerCompatible"`
}

StorageFormatInfo is a read-only negotiation view, not a full graph audit. ReaderCompatible says this binary understands the reported revision and all required feature bits; callers must still Open the database before use.

func InspectStorageFormat 

func InspectStorageFormat(path string) (StorageFormatInfo, error)

InspectStorageFormat validates current Meta checksums and reports its newest readable envelope without opening the database for mutation.

type StorageLimits 

type StorageLimits struct{ MaxFileBytes uint64 }

StorageLimits bounds the physical single-file high-water mark. Zero selects DefaultMaxFileBytes. The value must be a 16 KiB page multiple.

type StorageStats 

type StorageStats struct {
	Engine                     string                    `json:"engine"`
	RollbackProtected          bool                      `json:"rollbackProtected"`
	RollbackAnchorSequence     uint64                    `json:"rollbackAnchorSequence"`
	RollbackAnchorGeneration   uint64                    `json:"rollbackAnchorGeneration"`
	RollbackAnchorFailures     uint64                    `json:"rollbackAnchorFailures"`
	RollbackAnchorTimeout      time.Duration             `json:"rollbackAnchorTimeoutNanos"`
	RollbackAnchorNanos        uint64                    `json:"rollbackAnchorNanos"`
	RollbackAnchorMaxLatency   time.Duration             `json:"rollbackAnchorMaxLatencyNanos"`
	RollbackAnchorStore        RollbackAnchorStoreStatus `json:"rollbackAnchorStore"`
	PageSize                   uint64                    `json:"pageSize"`
	Generation                 uint64                    `json:"generation"`
	PhysicalPages              uint64                    `json:"physicalPages"`
	CommitSequence             uint64                    `json:"commitSequence"`
	OldestRetainedSequence     uint64                    `json:"oldestRetainedSequence"`
	RetainedCommits            uint64                    `json:"retainedCommits"`
	CommitRetentionMax         uint64                    `json:"commitRetentionMax"`
	CommitRetentionOverage     uint64                    `json:"commitRetentionOverage"`
	RetainedCommitBytes        uint64                    `json:"retainedCommitBytes"`
	CommitRetentionMaxBytes    uint64                    `json:"commitRetentionMaxBytes"`
	CommitRetentionByteOverage uint64                    `json:"commitRetentionByteOverage"`
	RetentionPrunedCommits     uint64                    `json:"retentionPrunedCommits"`
	RetentionPressureEvents    uint64                    `json:"retentionPressureEvents"`
	RetentionPressure          bool                      `json:"retentionPressure"`
	StorageUsedBytes           uint64                    `json:"storageUsedBytes"`
	StorageMaxBytes            uint64                    `json:"storageMaxBytes"`
	StorageByteOverage         uint64                    `json:"storageByteOverage"`
	StorageLimitRejections     uint64                    `json:"storageLimitRejections"`
	StorageQuotaExhausted      bool                      `json:"storageQuotaExhausted"`
	ActiveReaders              uint64                    `json:"activeReaders"`
	ActiveReplayLeases         uint64                    `json:"activeReplayLeases"`
	Documents                  uint64                    `json:"documents"`
	Collections                uint64                    `json:"collections"`
	ReusablePages              uint64                    `json:"reusablePages"`
	TreeSplits                 uint64                    `json:"treeSplits"`
	TreeMerges                 uint64                    `json:"treeMerges"`
	PersistentFreeSpace        bool                      `json:"persistentFreeSpace"`
	FreeSpaceLoads             uint64                    `json:"freeSpaceLoads"`
	FreeSpaceLoadFailures      uint64                    `json:"freeSpaceLoadFailures"`
	FreeSpacePublishes         uint64                    `json:"freeSpacePublishes"`
	FreeSpaceCandidateChecks   uint64                    `json:"freeSpaceCandidateChecks"`
	PageCache                  PageCacheStats            `json:"pageCache"`
	DocumentCache              DocumentCacheStats        `json:"documentCache"`
	CommitAttempts             uint64                    `json:"commitAttempts"`
	CommittedTransactions      uint64                    `json:"committedTransactions"`
	RejectedTransactions       uint64                    `json:"rejectedTransactions"`
	CommitNanos                uint64                    `json:"commitNanos"`
	CommitMaxLatency           time.Duration             `json:"commitMaxLatencyNanos"`
}

StorageStats describes the selected physical backend. Session counters reset on reopen; physical state and cache counters come from the backend itself.

type Update 

type Update map[string]any

type UpdateResult 

type UpdateResult struct{ MatchedCount, ModifiedCount int64 }

type Value 

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

Value is a closed tagged value. Its representation is private so callers cannot construct a tag/payload mismatch.

func Array 

func Array(v ...Value) Value

func Binary 

func Binary(v []byte) Value

func Bool 

func Bool(v bool) Value

func Float 

func Float(v float64) Value

func ID 

func ID(v DocumentID) Value

func Int 

func Int(v int64) Value

func Null 

func Null() Value

func Object 

func Object(v Document) Value

func String 

func String(v string) Value

func Time 

func Time(v time.Time) Value

Time stores millisecond precision, matching JavaScript Date and the wire contract. Precision is normalized at construction rather than silently lost during transport.

func UnmarshalWireValue 

func UnmarshalWireValue(data []byte, limits QueryLimits) (Value, error)

UnmarshalWireValue decodes one closed, typed wire value using the same depth/item/byte limits as query operands. It is suitable for data-only protocol arguments such as RPC; it never evaluates source or callbacks.

func ValueOf 

func ValueOf(x any) (Value, error)

func (Value) ArrayValue 

func (v Value) ArrayValue() ([]Value, bool)

func (Value) BinaryValue 

func (v Value) BinaryValue() ([]byte, bool)

func (Value) Bool 

func (v Value) Bool() (bool, bool)

func (Value) Clone 

func (v Value) Clone() Value

func (Value) Equal 

func (v Value) Equal(other Value) bool

func (Value) Float64 

func (v Value) Float64() (float64, bool)

func (Value) IDValue 

func (v Value) IDValue() (DocumentID, bool)

func (Value) Int64 

func (v Value) Int64() (int64, bool)

func (Value) Kind 

func (v Value) Kind() Kind

func (Value) ObjectValue 

func (v Value) ObjectValue() (Document, bool)

func (Value) StringValue 

func (v Value) StringValue() (string, bool)

func (Value) TimeValue 

func (v Value) TimeValue() (time.Time, bool)

type VerificationReport 

type VerificationReport struct {
	SchemaVersion              int           `json:"schemaVersion"`
	Verified                   bool          `json:"verified"`
	Format                     StorageFormat `json:"format"`
	Revision                   uint16        `json:"revision"`
	DatabaseIDHex              string        `json:"databaseIdHex"`
	MetaGeneration             uint64        `json:"metaGeneration"`
	CommitSequence             uint64        `json:"commitSequence"`
	OldestRetainedSequence     uint64        `json:"oldestRetainedSequence"`
	RequiredFeatures           uint64        `json:"requiredFeatures"`
	OptionalFeatures           uint64        `json:"optionalFeatures"`
	ValidMetaSlots             int           `json:"validMetaSlots"`
	FileBytes                  uint64        `json:"fileBytes"`
	TrailingBytes              uint64        `json:"trailingBytes"`
	PhysicalPages              uint64        `json:"physicalPages"`
	CommittedPhysicalPages     uint64        `json:"committedPhysicalPages"`
	ReachablePages             uint64        `json:"reachablePages"`
	ReclaimablePages           uint64        `json:"reclaimablePages"`
	PersistentFreeSpace        bool          `json:"persistentFreeSpace"`
	FreeSpaceValid             bool          `json:"freeSpaceValid"`
	IndexContentsVerified      bool          `json:"indexContentsVerified"`
	IndexBuildContentsVerified bool          `json:"indexBuildContentsVerified"`
	SHA256                     string        `json:"sha256"`
}

VerificationReport is a schema-versioned receipt for a full, read-only protected-page graph and published-index semantic audit. ReclaimablePages is informational; verification never installs a free pool or publishes maintenance metadata.

func VerifyFile 

func VerifyFile(ctx context.Context, path string) (VerificationReport, error)

VerifyFile performs an offline, non-mutating audit of an existing file. It takes a non-blocking shared advisory lock, so an active writer fails with ErrDatabaseLocked. It never creates, truncates, repairs, reclaims, or advances the database. Meta inspection alone is cheaper; this method walks every page protected by both valid Meta roots, recomputes published and provable shadow Secondary keys from canonical Primary documents in both directions, and hashes the file. Legacy caught-up builds lacking an applied CatalogRoot remain readable but report IndexBuildContentsVerified=false.

type WriteTransaction 

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

WriteTransaction is a short-lived snapshot write view. It provides point operations with optimistic serializable commit validation. Values returned from it are isolated clones.

A transaction is active only during its handler callback. Handlers must not retain it or call normal DB/Collection methods from inside the callback.

func (*WriteTransaction) DeleteOne 

func (tx *WriteTransaction) DeleteOne(collection string, id DocumentID) error

DeleteOne stages a point delete. Deleting a document inserted earlier in the same callback cancels that insert without producing a storage mutation.

func (*WriteTransaction) Find 

func (tx *WriteTransaction) Find(collection string, query QuerySpec) (QuerySnapshot, error)

Find evaluates query against the transaction's immutable snapshot plus its own staged point writes. It installs a collection snapshot fence, so any concurrent document or published-index change in that collection causes the eventual commit to return ErrWriteConflict rather than admitting a phantom.

The first range-read primitive intentionally uses a collection-wide fence. It is serializable and independent of a process-local index plan; a future narrower predicate-fence implementation can refine conflicts without weakening this API's correctness contract.

func (*WriteTransaction) GetOne 

func (tx *WriteTransaction) GetOne(collection string, id DocumentID) (Document, error)

GetOne returns one document by intrinsic ID from the transaction's current view, including earlier point mutations in the same callback.

func (*WriteTransaction) InsertOne 

func (tx *WriteTransaction) InsertOne(collection string, document Document) (DocumentID, error)

InsertOne stages one insert and returns its generated or supplied ID.

func (*WriteTransaction) MeldbaseStageSystemMutation 

func (tx *WriteTransaction) MeldbaseStageSystemMutation(mutation systemrecord.Mutation, onCommit func(uint64)) error

MeldbaseStageSystemMutation is first-party composite-transaction plumbing. Its internal parameter type prevents external applications from accessing the private System tree. onCommit runs synchronously after the durable root is published and before the matching business ChangeBatch becomes visible; it must be bounded, non-blocking and must not call back into the database.

func (*WriteTransaction) ReplaceOne 

func (tx *WriteTransaction) ReplaceOne(collection string, id DocumentID, document Document) error

ReplaceOne stages a full replacement for an existing document. The supplied document may omit _id; if present it must equal id.

func (*WriteTransaction) UpdateOne 

func (tx *WriteTransaction) UpdateOne(collection string, id DocumentID, mutation MutationSpec) error

UpdateOne applies one already compiled, data-only mutation to the transaction's current document view. Earlier writes in the same transaction are visible and the intrinsic _id remains immutable.

type WriteTransactionStats 

type WriteTransactionStats struct {
	Active    uint64 `json:"active"`
	Started   uint64 `json:"started"`
	Committed uint64 `json:"committed"`
	Noops     uint64 `json:"noops"`
	Conflicts uint64 `json:"conflicts"`
	Aborted   uint64 `json:"aborted"`
}

WriteTransactionStats describes public optimistic point transactions. Every started callback reaches exactly one terminal counter. These aggregates do not contain collection, document, actor, or callback identifiers.

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.