cursor

package
v0.0.9 Latest Latest
Warning

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

 Go to latest Published: Aug 18, 2026 License: GPL-3.0 Imports: 16 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func CodeOf 

func CodeOf(err error) api.ErrorCode

CodeOf returns a stable public error code for registry admission failures.

func EntryBytes 

func EntryBytes(accounting EntryAccounting) (uint64, error)

EntryBytes returns the dynamic bytes retained by one entry.

func LineageBytes 

func LineageBytes(accounting LineageAccounting) (uint64, error)

LineageBytes returns dynamic bytes; fixed arena/index capacity is excluded.

func SuccessorBytes 

func SuccessorBytes(state State, result api.Result) (uint64, error)

SuccessorBytes returns the exact cursor bytes retained by one successor state and the memoized result of its parent.

func UsedSlots 

func UsedSlots(accounting LineageAccounting) (uint64, error)

UsedSlots returns resident plus semantic tombstone plus reserved slots.

Types

type Clock 

type Clock interface {
	Now() time.Time
}

Clock is the minimal registry clock contract. Production installs wallClock.

type Compute 

type Compute func(ctx context.Context, working State, resources Resources) Outcome

Compute advances one separately owned working state.

type DynamicInitial 

type DynamicInitial struct {
	State       State
	Root        *rootfs.Lease
	SummaryPlan ReservationUse
}

DynamicInitial creates one project/search lineage with a terminal-summary credit.

type EntryAccounting 

type EntryAccounting struct {
	StateBytes uint64
	MemoBytes  uint64
}

EntryAccounting describes cursor-owned backing retained by one token entry.

type EntryRef 

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

EntryRef remains safe across arena reuse because every claim carries a generation.

type InitialCommit 

type InitialCommit struct {
	Token       Token
	Publication *InitialPublication
}

InitialCommit couples the first token with its transactional publication owner.

type InitialPublication 

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

InitialPublication keeps rollback armed until the complete response is written.

func (*InitialPublication) Abort 

func (publication *InitialPublication) Abort()

Abort rolls back an armed lineage and returns the transferred work slot.

func (*InitialPublication) Commit 

func (publication *InitialPublication) Commit() error

Commit publishes the lineage and returns the transferred work slot.

func (*InitialPublication) MarkNoCommit 

func (publication *InitialPublication) MarkNoCommit()

MarkNoCommit rolls back publication but leaves the running worker charged.

func (*InitialPublication) Prepare 

func (publication *InitialPublication) Prepare() error

Prepare makes a provisional lineage lookup-visible while retaining rollback.

func (*InitialPublication) Release 

func (publication *InitialPublication) Release()

Release is invoked by WorkLease.WorkerReturned and rolls back only while armed.

type Layout 

type Layout struct {
	MaxEntries          uint64
	IndexSlots          uint64
	WordBytes           uint64
	TokenIndexBacking   uint64
	LineageIndexBacking uint64
	EntryArenaBacking   uint64
	LineageArenaBacking uint64
	SliceDescriptors    uint64
	ScalarBytes         uint64
	Total               uint64
}

Layout is the complete fixed allocation retained by one registry.

func ContainerLayout 

func ContainerLayout(maxEntries uint64) (Layout, error)

ContainerLayout computes fixed parallel-column backing without allocator guesses.

type LineageAccounting 

type LineageAccounting struct {
	Resident      uint64
	Tombstones    uint64
	ReservedSlots uint64
	EntryBytes    uint64
	SharedBytes   uint64
	RootBytes     uint64
	ReservedBytes uint64
}

LineageAccounting describes dynamic bytes and logical slots for one lineage.

type Outcome 

type Outcome struct {
	Result      api.Result
	Successor   State
	Reservation ReservationUse
	Progress    ProgressProof
	Finalize    ResultFinalizer
}

Outcome is either terminal Result or a Successor plus token-aware Finalize callback.

type ProgressKind 

type ProgressKind uint8

ProgressKind is the closed set of monotonic continuation transitions. 

const (
	ProgressOutputKey ProgressKind = iota + 1
	ProgressReadItem
	ProgressSummary
	ProgressTraversal
)

type ProgressProof 

type ProgressProof struct {
	Kind        ProgressKind
	BeforeValue uint64
	AfterValue  uint64
	Before      [32]byte
	After       [32]byte
}

ProgressProof prevents a partial cursor from reproducing the same state forever.

func (ProgressProof) Valid 

func (proof ProgressProof) Valid() bool

Valid reports whether this proof strictly advances its selected dimension.

type ReadInitial 

type ReadInitial struct {
	State    State
	Shared   SharedAllocation
	PagePlan ReadPageReservation
}

ReadInitial creates one immutable read lineage and charges shared backing once.

type ReadPageReservation 

type ReadPageReservation struct {
	Pages uint32
	Slots uint64
	Bytes uint64
}

ReadPageReservation reserves every page after the already-rendered first page.

type Registry 

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

Registry owns all cursor state for exactly one MCP connection.

func New 

func New(cfg config.Runtime) (*Registry, error)

New constructs one fixed-capacity connection-local registry.

func (*Registry) Close 

func (registry *Registry) Close() error

Close invalidates every token and releases fixed storage after the last pin.

func (*Registry) CommitDynamicInitial 

func (registry *Registry) CommitDynamicInitial(request DynamicInitial, work *serverruntime.WorkLease) (commit InitialCommit, err error)

CommitDynamicInitial installs a provisional project/search lineage.

func (*Registry) CommitReadInitial 

func (registry *Registry) CommitReadInitial(request ReadInitial, work *serverruntime.WorkLease) (InitialCommit, error)

CommitReadInitial installs a provisional immutable read plan.

func (*Registry) Continue 

func (registry *Registry) Continue(ctx context.Context, token Token, tool api.ToolName, cwdID uint64, waiter Waiter, compute Compute, work *serverruntime.WorkLease)

Continue joins replay/singleflight for one scoped cursor token.

func (*Registry) Lookup 

func (registry *Registry) Lookup(token Token) (EntryRef, api.ErrorCode)

Lookup resolves one connection-local token and refreshes whole-lineage recency.

type ReservationKind 

type ReservationKind uint8

ReservationKind identifies the only two pre-admitted continuation plans. 

const (
	ReadPagePlan ReservationKind = iota + 1
	BroadSummaryFinal
)

type ReservationUse 

type ReservationUse struct {
	Kind            ReservationKind
	Slots           uint64
	Bytes           uint64
	MustTerminalize bool
}

ReservationUse describes one exact reservation or materialization transition.

type Resources 

type Resources struct {
	Root rootfs.Borrowed
}

Resources exposes only a continuation-scoped borrowed root.

type ResultFinalizer 

type ResultFinalizer func(child Token) (api.Result, error)

ResultFinalizer renders a partial result after the registry derives its child token.

type SharedAllocation 

type SharedAllocation interface {
	Digest() [32]byte
	Footprint() uint64
}

SharedAllocation is immutable backing shared by every entry in a read lineage.

type State 

type State interface {
	Tool() api.ToolName
	CWDID() uint64
	Digest() [32]byte
	SharedDigest() ([32]byte, bool)
	Footprint() uint64
	CloneForCompute() State
}

State is an immutable, cursor-owned continuation snapshot.

type Token 

type Token [16]byte

Token is one opaque, connection-bound 128-bit cursor identifier.

func ParseToken 

func ParseToken(raw string) (Token, api.ErrorCode)

ParseToken accepts only the canonical unpadded base64url representation.

func (Token) String 

func (token Token) String() string

String returns the canonical unpadded base64url representation.

type Waiter 

type Waiter interface {
	Deliver(api.Result)
	Cancelled() <-chan struct{}
	CloseWithoutResponse()
}

Waiter keeps request-specific response state outside cursor accounting.

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.