world

type AccessObjectCb func(bcs *block.Cursor) error

type AccessWorldStateFunc = func(
	ctx context.Context,
	ref *bucket.ObjectRef,
	cb func(*bucket_lookup.Cursor) error,
) error

type AuthenticatedOperation interface {
	Operation
	AuthenticatedOperation()
}

type BatchEngine struct {
	// Engine supplies storage and transactions outside an active batch.
	Engine
}

type BuildCursorFn func(ctx context.Context) (*bucket_lookup.Cursor, error)

type BusEngine = RefCountEngine

type CayleyHandle interface {
	graph.QuadStore
}

type ChangeFilter func(changes *ChangeSet) bool

type ChangeIndex[T comparable] struct {
	// contains filtered or unexported fields
}

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

type ChangeSet struct {
	// Unknown means the changes could not be determined.
	// Every ReadSet is touched by an unknown ChangeSet.
	Unknown bool
	// Keys are the object keys that were set, deleted, renamed, or revised.
	// A rename lists both the old and the new key. A revision that only
	// follows a set or deleted quad naming the object is reported through
	// Quads alone.
	Keys []string
	// Quads are the graph quads that were set or deleted, each field spelled
	// as the graph stores it.
	Quads []GraphQuad
}

type ChangeWatcher interface {
	// WatchChanges calls cb with each later seqno whose changes touches
	// accepts, starting after afterSeqno, and the accepted changes since the
	// previous call. Changes touches rejects never wake the watcher. Calls
	// coalesce while cb runs. Returns when ctx is canceled or cb returns an
	// error.
	WatchChanges(ctx context.Context, afterSeqno uint64, touches ChangeFilter, cb func(seqno uint64, changes *ChangeSet) error) error
}

type CommitReceipt interface {
	Done() <-chan struct{}
	Wait(context.Context) error
}

type Controller interface {
	// Controller indicates this is a controller-bus controller.
	controller.Controller
	// GetWorldEngine waits for the engine to be built.
	GetWorldEngine(context.Context) (Engine, error)
}

type Engine interface {
	// OperationAuthor returns this engine's signing device and its accepted person.
	// Unsigned engines return an empty device; callers requiring authorship reject it.
	OperationAuthor(ctx context.Context) (peer.ID, string, error)
	// NewTransaction returns a new transaction against the store.
	// A read transaction retains one immutable revision until Discard. Use
	// NewEngineWorldState for live reads and object revision watches.
	// Indicate write if the transaction will not be read-only.
	// Always call Discard() after you are done with the transaction.
	// Check GetReadOnly, might not return a write tx if write=true.
	NewTransaction(ctx context.Context, write bool) (Tx, error)

	// Sync fences durable storage and advances the durable world head.
	// Runs the block barrier so every block written so far is durable, then
	// commits the current in-memory root to the durable head ordered after the
	// barrier. Returns true if a durability fence was applied, false if the
	// store is always-durable and no fence was required.
	Sync(ctx context.Context) (bool, error)

	// SyncThrough returns once every commit with seqno <= seqno is durable and
	// covered by the durable head. It returns without a fence when the durable
	// head already covers seqno, and it waits for commits up to seqno to be
	// published but not for commits admitted after seqno. It returns the
	// durable seqno, >= seqno. An engine whose commits are durable on write
	// returns at once.
	SyncThrough(ctx context.Context, seqno uint64) (durable uint64, err error)

	// WorldStorage provides access to the world storage via bucket cursors.
	WorldStorage

	// StageWorldState opens a staging scope for writes outside a transaction.
	// Build through the stage, adopt the result in a transaction, then
	// release the stage after that transaction returns.
	StageWorldState(ctx context.Context) (WorldStage, error)

	// WorldWaitSeqno allows waiting for the world seqno to change.
	WorldWaitSeqno

	// WaitObjectRev waits until the object at key reaches rev and returns its
	// revision. Returns ErrObjectNotFound if the object does not exist, unless
	// ignoreNotFound is set, in which case it waits for the object to appear.
	// Use WaitObjectRevBySeqno when the engine cannot watch individual keys.
	WaitObjectRev(ctx context.Context, key string, rev uint64, ignoreNotFound bool) (uint64, error)
}

type EngineConfig interface {
	config.Config
	// GetEngineId returns the ID the controller serves its engine under.
	GetEngineId() string
}

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

type EngineResolver = refcount.RefCountResolver[*Engine]

type ForkableWorldState interface {
	WorldState

	// Fork forks the current state into a new state.
	Fork(ctx context.Context) (WorldState, error)
}

type GraphEdgeBucket struct {
	// OriginObjectKey is the requested origin object key.
	OriginObjectKey string
	// Outgoing contains quads where the origin is the subject.
	Outgoing []GraphQuad
	// Incoming contains quads where the origin is the object.
	Incoming []GraphQuad
	// OutgoingTruncated indicates more outgoing edges matched than were returned.
	OutgoingTruncated bool
	// IncomingTruncated indicates more incoming edges matched than were returned.
	IncomingTruncated bool
}

type GraphEdgeBucketDirection int

type GraphEdgeBucketQuery struct {
	// OriginObjectKeys are object keys whose graph edges should be grouped.
	OriginObjectKeys []string
	// Predicate optionally restricts grouped edges.
	Predicate string
	// LimitPerOrigin is the maximum edge count returned per origin direction.
	LimitPerOrigin uint32
	// Direction selects which edge directions are included.
	Direction GraphEdgeBucketDirection
}

type GraphPathDirection int

type GraphPathQuery struct {
	// StartKeys is the list of object keys where traversal starts.
	StartKeys []string
	// Steps is the ordered traversal to execute.
	Steps []GraphPathStep
	// ResultLimit is the maximum number of final object keys returned.
	ResultLimit uint32
	// IncludeQuads includes traversed quads in the result.
	IncludeQuads bool
}

type GraphPathQueryResult struct {
	// ObjectKeys is the set of reached object keys.
	ObjectKeys []string
	// Quads is the set of traversed quads when requested.
	Quads []GraphQuad
}

type GraphPathStep struct {
	// Direction is the edge direction to follow.
	Direction GraphPathDirection
	// Predicate is the graph predicate to match.
	Predicate string
	// Limit is the maximum number of quads inspected per current key.
	Limit uint32
}

type GraphQuad interface {
	// GetSubject returns the subject field.
	GetSubject() string
	// GetPredicate returns the predicate field.
	GetPredicate() string
	// GetObj returns the object field.
	GetObj() string
	// GetLabel returns the label field, which is usually empty.
	GetLabel() string
}

type IndexedChangeWatcher interface {
	ChangeWatcher
	// WatchIndexedChanges is WatchChanges for the changes interest accepts. A
	// change that names none of the interest's keys or quad fields never tests
	// or wakes the watcher.
	WatchIndexedChanges(ctx context.Context, afterSeqno uint64, interest *ChangeInterest, cb func(seqno uint64, changes *ChangeSet) error) error
}

type LookupOp = func(ctx context.Context, operationTypeID string) (Operation, error)

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

type LookupOpSlice []LookupOp

type LookupWorldEngine interface {
	// Directive indicates LookupWorldEngine is a directive.
	directive.Directive

	// LookupWorldEngineID returns a specific world engine we are looking for.
	// Can be empty.
	LookupWorldEngineID() string
}

type LookupWorldEngineValue = Engine

type LookupWorldOp interface {
	// Directive indicates LookupWorldOp is a directive.
	directive.Directive

	// LookupWorldOpOperationTypeID returns the operation type ID.
	// Cannot be empty.
	LookupWorldOpOperationTypeID() string
	// LookupWorldOpEngineID returns the world engine ID.
	// Can be empty.
	LookupWorldOpEngineID() string
}

type LookupWorldOpValue = LookupOp

type ObjectBody struct {
	// ObjectKey is the requested object key.
	ObjectKey string
	// Body is the transformed root block data when the object exists.
	Body []byte
	// Rev is the object revision observed with Body.
	Rev uint64
	// ModSeqno is the World seqno after the last commit that changed the
	// object. Zero when the object state does not report it.
	ModSeqno uint64
	// Exists reports whether the object key exists.
	Exists bool
}

type ObjectBodyBatcher interface {
	// GetObjectBodiesBatch returns object bodies for object keys.
	GetObjectBodiesBatch(ctx context.Context, keys []string) ([]*ObjectBody, error)
}

type ObjectBodyPageBatcher interface {
	// GetObjectBodiesBatchPage returns bodies and the number of keys consumed.
	GetObjectBodiesBatchPage(ctx context.Context, keys []string, byteBudget int) ([]*ObjectBody, uint32, error)
}

type ObjectBodyPageSeqnoBatcher interface {
	// GetObjectBodiesBatchPageWithSeqno returns bodies, consumed keys, and the
	// World sequence number observed by the read transaction.
	GetObjectBodiesBatchPageWithSeqno(ctx context.Context, keys []string, byteBudget int) ([]*ObjectBody, uint32, uint64, error)
}

type ObjectBodyResult[T block.Block] struct {
	// ObjectKey is the requested object key.
	ObjectKey string
	// Body is the decoded object body when the object exists.
	Body T
	// Exists reports whether the object key exists.
	Exists bool
}

type ObjectBodyTooLargeError struct {
	// ObjectKey is the key whose encoded entry exceeds the page budget.
	ObjectKey string
	// EncodedSize is the serialized size of the object body response entry.
	EncodedSize int
	// ByteBudget is the maximum encoded size allowed for one page.
	ByteBudget int
}

type ObjectIterator interface {
	// Err returns any error that has closed the iterator.
	// May return context.Canceled if closed.
	Err() error

	// Valid returns if the iterator points to a valid entry.
	//
	// If err is set, returns false.
	Valid() bool

	// Key returns the current entry key, or nil if not valid.
	Key() string

	// Next advances to the next entry and returns Valid.
	Next() bool

	// Seek moves the iterator to the first key >= the provided key (or <= in reverse mode).
	// Pass an empty string to seek to the beginning (or end if reversed).
	// Seek has two failure modes:
	//  - return an error without modifying the iterator.
	//  - set the iterator Err to the error and return nil.
	Seek(k string) error

	// Close releases the iterator.
	Close()
}

type ObjectModSeqnoReader interface {
	// GetModSeqno returns the World seqno after the last commit that changed
	// the object.
	GetModSeqno(ctx context.Context) (uint64, error)
}

type ObjectOperation interface {
	Operation

	// ApplyWorldObjectOp applies the operation to a world object handle. It
	// returns false, ErrUnhandledOp if the operation cannot handle an object op.
	ApplyWorldObjectOp(
		ctx context.Context,
		le *logrus.Entry,
		objectHandle ObjectState,
		sender peer.ID,
	) (sysErr bool, err error)
}

type ObjectPurger interface {
	// PurgeObject removes the object entry at key and every graph quad naming
	// it, without reading the object's record or root. The deletion change
	// keeps no reference to the record, so nothing still reaches its blocks.
	// Returns false, nil if not found.
	PurgeObject(ctx context.Context, key string) (bool, error)
}

type ObjectRevWaiter interface {
	// WaitObjectRev waits until the object at key reaches rev and returns its
	// revision, with the contract of Engine.WaitObjectRev.
	WaitObjectRev(ctx context.Context, key string, rev uint64, ignoreNotFound bool) (uint64, error)
}

type ObjectRootRef struct {
	// ObjectKey is the object key.
	ObjectKey string
	// RootRef is the current object root ref.
	RootRef *bucket.ObjectRef
	// Rev is the object revision.
	Rev uint64
	// Exists is true when the object exists.
	Exists bool
}

type ObjectRootRefBatcher interface {
	// GetObjectRootRefsBatch returns object root refs for object keys.
	GetObjectRootRefsBatch(ctx context.Context, keys []string) ([]*ObjectRootRef, error)
}

type ObjectState interface {
	// GetKey returns the key this state object is for.
	GetKey() string

	// GetRootRef returns the root reference.
	// Returns the revision number.
	GetRootRef(ctx context.Context) (*bucket.ObjectRef, uint64, error)

	// AccessWorldState builds a bucket lookup cursor with an optional ref.
	// If the ref is empty, will default to the object RootRef.
	// If the ref Bucket ID is empty, uses the same bucket + volume as the world.
	// The lookup cursor will be released after cb returns.
	AccessWorldState(
		ctx context.Context,
		ref *bucket.ObjectRef,
		cb func(*bucket_lookup.Cursor) error,
	) error

	// SetRootRef changes the root reference of the object.
	// Increments the revision of the object if changed.
	// Returns revision just after the change was applied.
	SetRootRef(ctx context.Context, nref *bucket.ObjectRef) (uint64, error)

	// ApplyObjectOp applies a batch operation at the object level.
	// The handling of the operation is operation-type specific.
	// Returns the revision following the operation execution.
	// If nil is returned for the error, implies success.
	// If sysErr is set, the error is treated as a transient system error.
	// Returns rev, sysErr, err
	ApplyObjectOp(
		ctx context.Context,
		op Operation,
		opSender peer.ID,
	) (rev uint64, sysErr bool, err error)

	// IncrementRev increments the revision of the object.
	// Returns revision just after the change was applied.
	IncrementRev(ctx context.Context) (uint64, error)

	// WaitRev waits until the object rev is >= the specified.
	// Returns ErrObjectNotFound if the object is deleted.
	// If ignoreNotFound is set, waits for the object to exist.
	// Returns the new rev.
	WaitRev(ctx context.Context, rev uint64, ignoreNotFound bool) (uint64, error)
}

type Operation interface {
	// Block indicates this operation is serializable to a block.
	block.Block

	// TypeID returns the operation type identifier.
	TypeID() string

	// ApplyWorldOp applies the operation as a world operation. It returns
	// false, ErrUnhandledOp if the operation cannot handle a world op.
	ApplyWorldOp(
		ctx context.Context,
		le *logrus.Entry,
		worldHandle WorldState,
		sender peer.ID,
	) (sysErr bool, err error)
}

type OperationRejection struct {
	Code    string
	Message string
}

type PayloadOperation interface {
	Operation

	// GetPayloadRefs returns the roots of the operation's payload.
	GetPayloadRefs() []*block.BlockRef
}

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

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

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

type RefCountTx struct {
	WorldState
	// contains filtered or unexported fields
}

type ReplacingController interface {
	Controller
	// AcquireWorldEngine waits for the served engine and holds it open until
	// release is called.
	AcquireWorldEngine(ctx context.Context) (eng Engine, release func(), err error)
	// WaitWorldEngineReplaced waits until eng is no longer the engine the
	// controller serves.
	WaitWorldEngineReplaced(ctx context.Context, eng Engine) error
}

type RootRetainingEngine interface {
	// SetRetainedRoot retains the World root ref under name, replacing the
	// root the name held. ref must be the accepted head, with its blocks in
	// the World's storage. An empty ref releases the name.
	SetRetainedRoot(ctx context.Context, name string, ref *block.BlockRef) error
}

type Schema map[string]func() any

type SubmittableTx interface {
	Tx
	Submit(context.Context) (CommitReceipt, error)
}

type Tx interface {
	// WorldState contains the world read/write ops.
	WorldState
	// Tx contains the transaction Commit/Discard ops.
	tx.Tx
}

type ValidatedOperation interface {
	Operation

	// Validate performs cursory validation of the operation.
	// Should not block.
	Validate() error
}

type View[T any] interface {
	// EqualVT reports whether two messages carry the same content.
	EqualVT(T) bool
}

type WatchViewOptions struct {
	// AfterSeqno is a seqno the caller already holds the view at. When it is
	// above zero, the first evaluation waits for the World to pass it.
	AfterSeqno uint64
	// MinInterval is the least time between the starts of two evaluations. A
	// burst of touching commits reruns the view once per interval, and the rerun
	// reads the newest head. Zero reruns as soon as a change or deadline arrives.
	MinInterval time.Duration
}

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

type WorldStage interface {
	// WorldStorage builds cursors whose writes the stage owns.
	WorldStorage

	// ReleaseRoots drops the stage's ownership of roots built through it. Call
	// it once the transaction that references them has returned. Each root
	// then survives only through a committed parent. The stage stays open.
	ReleaseRoots(ctx context.Context, roots []*block.BlockRef) error

	// Release ends the stage. Writes through its cursors fail afterward.
	Release()
}

type WorldState interface {
	// GetReadOnly returns if the state is read-only.
	GetReadOnly() bool

	// Sync fences the block writes made through this state durable.
	// Returns true if a durability fence was applied, false if the underlying
	// store is always-durable. Advancing the durable head is the Engine's
	// responsibility (see Engine.Sync); a bare WorldState only fences blocks.
	Sync(ctx context.Context) (bool, error)

	// ListObjectsWithType returns distinct typed keys in graph-index order,
	// strictly after startAfter. Limit must be non-zero; more marks another page.
	// The World must remain unchanged for exactly-once traversal across pages.
	ListObjectsWithType(ctx context.Context, typeID, startAfter string, limit uint32) ([]string, bool, error)

	// WorldStorage accesses the world storage.
	WorldStorage

	// StageWorldState opens a staging scope for writes outside a transaction.
	// Build through the stage, adopt the result through this state, then
	// release the stage after the adopting call returns. An engine-level state
	// opens an engine stage. A write transaction adopts the build only when it
	// commits, after the adopting call returns, so its stage writes through the
	// transaction's own storage and Release does nothing. A read-only state
	// returns tx.ErrNotWrite.
	StageWorldState(ctx context.Context) (WorldStage, error)

	// WorldStateObject contains the object APIs.
	WorldStateObject
	// WorldStateGraph contains the graph APIs.
	WorldStateGraph
	// WorldStateOp contains the operation APIs.
	WorldStateOp

	// WorldWaitSeqno waits for the world state to change.
	WorldWaitSeqno
}

type WorldStateGraph interface {
	// AccessCayleyGraph calls a callback with a temporary Cayley graph handle.
	// All accesses of the handle should complete before returning cb.
	// Try to make access (queries) as short as possible.
	// Write operations will fail if the store is read-only.
	// Remote WorldState implementations may reject this local-only Cayley handle
	// access; use QueryGraphPath or exact graph lookup for remote traversal.
	AccessCayleyGraph(ctx context.Context, write bool, cb func(ctx context.Context, h CayleyHandle) error) error

	// LookupGraphQuads searches for graph quads in the store.
	// If the filter fields are empty, matches any for that field.
	// If not found, returns nil, nil
	// If limit is set, stops after finding that number of matching quads.
	LookupGraphQuads(ctx context.Context, filter GraphQuad, limit uint32) ([]GraphQuad, error)

	// LookupGraphQuadsBatch searches for graph quads for each filter in one
	// World graph read operation. Each result set preserves the corresponding
	// filter index and applies the limit independently.
	LookupGraphQuadsBatch(ctx context.Context, filters []GraphQuad, limitPerFilter uint32) ([][]GraphQuad, error)

	// QueryGraphPath executes a bounded graph traversal without exposing a Cayley handle.
	QueryGraphPath(ctx context.Context, query *GraphPathQuery) (*GraphPathQueryResult, error)

	// SetGraphQuad sets a quad in the graph store.
	// Subject: must be an existing object IRI: <object-key>
	// Predicate: a predicate string, e.x. IRI: <ref>
	// Object: an existing object IRI: <object-key>
	// If already exists, returns nil.
	SetGraphQuad(ctx context.Context, q GraphQuad) error

	// DeleteGraphQuad deletes a quad from the graph store.
	// Note: if quad did not exist, returns nil.
	DeleteGraphQuad(ctx context.Context, q GraphQuad) error

	// DeleteGraphObject deletes all quads with Subject or Object set to value.
	// Note: value should be the object key, NOT the object key <iri> format.
	DeleteGraphObject(ctx context.Context, value string) error
}

type WorldStateObject interface {
	// GetObject looks up an object by key.
	// Returns nil, false if not found.
	GetObject(ctx context.Context, key string) (ObjectState, bool, error)

	// IterateObjects returns an iterator with the given object key prefix.
	// The prefix is NOT clipped from the output keys.
	// Keys are returned in sorted order.
	// Must call Next() or Seek() before valid.
	// Call Close when done with the iterator.
	// Any init errors will be available via the iterator's Err() method.
	IterateObjects(ctx context.Context, prefix string, reversed bool) ObjectIterator

	// CreateObject creates a object with a key and initial root ref.
	// Returns ErrObjectExists if the object already exists.
	// Appends a OBJECT_SET change to the changelog.
	CreateObject(ctx context.Context, key string, rootRef *bucket.ObjectRef) (ObjectState, error)

	// RenameObject renames an object key and updates associated graph quads.
	// If descendants is true, all objects under oldKey + "/" are renamed
	// to the matching newKey + "/" prefix in the same operation.
	// Returns ErrObjectNotFound if the old object key does not exist.
	// Returns ErrObjectExists if the new object key already exists.
	RenameObject(ctx context.Context, oldKey, newKey string, descendants bool) (ObjectState, error)

	// DeleteObject deletes an object and associated graph quads by ID.
	// Calls DeleteGraphObject internally.
	// Returns false, nil if not found.
	DeleteObject(ctx context.Context, key string) (bool, error)

	// HasObject reports whether an object exists at key. Implementations may
	// answer from transaction-local knowledge without a storage read; on a miss
	// they fall back to the underlying object lookup.
	HasObject(ctx context.Context, key string) (bool, error)
}

type WorldStateOp interface {
	// ApplyWorldOp applies a batch operation at the world level.
	// The handling of the operation is operation-type specific.
	// Returns the seqno following the operation execution.
	// If nil is returned for the error, implies success.
	// If sysErr is set, the error is treated as a transient system error.
	// Must support recursive calls to ApplyWorldOp / ApplyObjectOp.
	// Returns seqno, sysErr, err.
	ApplyWorldOp(
		ctx context.Context,
		op Operation,
		opSender peer.ID,
	) (seqno uint64, sysErr bool, err error)
}

type WorldStorage interface {
	// BuildStorageCursor builds a cursor to the world storage with an empty ref.
	// The cursor should be released independently of the WorldState.
	// Be sure to call Release on the cursor when done.
	BuildStorageCursor(ctx context.Context) (*bucket_lookup.Cursor, error)

	// AccessWorldState builds a bucket lookup cursor with an optional ref.
	// If the ref is empty, returns a cursor pointing to the root world state.
	// The lookup cursor will be released after cb returns.
	AccessWorldState(
		ctx context.Context,
		ref *bucket.ObjectRef,
		cb func(*bucket_lookup.Cursor) error,
	) error
}

type WorldWaitSeqno interface {
	// GetSeqno returns the current seqno of the world state.
	// This is also the sequence number of the most recent change.
	// Initializes at 0 for initial world state.
	GetSeqno(ctx context.Context) (uint64, error)

	// WaitSeqno waits for the seqno of the world state to be >= value.
	// Returns the seqno when the condition is reached.
	// If value == 0, this might return immediately unconditionally.
	WaitSeqno(ctx context.Context, value uint64) (uint64, error)
}