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 BuildCursorFn func(ctx context.Context) (*bucket_lookup.Cursor, error)

type BusEngine = RefCountEngine

type CayleyHandle interface {
	graph.QuadStore
}

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 {
	// NewTransaction returns a new transaction against the store.
	// 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)

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

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

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.
	// (empty in most cases)
	GetLabel() string
}

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 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 nil 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 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

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

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

	// ApplyWorldOp applies the operation as a world operation.
	// 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)

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

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

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

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

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

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)

	// WorldStorage accesses the world storage.
	WorldStorage
	// 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)
}

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)
}