threadstore

type AlreadyExistsError ¶

type AlreadyExistsError struct {
	Key string
}

AlreadyExistsError is returned by a conditional Finalize when Key already has an active mapping. Unwrap returns ErrAlreadyExists.

func (e *AlreadyExistsError) Error() string

func (e *AlreadyExistsError) ThreadAlreadyExists() bool

func (e *AlreadyExistsError) Unwrap() error

type BusyError ¶

type BusyError struct {
	Target string
}

BusyError is returned by AcquireLease when the target is exclusively held by another owner. Unwrap returns ErrBusy.

func (e *BusyError) Error() string

func (e *BusyError) Unwrap() error

type FinalizeRequest ¶

type FinalizeRequest struct {
	Record     Record
	PreviousID string
	// Key is the thread key whose active mapping is rebound when
	// RebindActive is set.
	Key        string
	HeldLeases []Lease
	// ArchiveOld archives the PreviousID record (resume-fallback paths keep
	// the old conversation addressable for audit).
	ArchiveOld bool
	// RebindActive points the Key's active mapping at Record.ID.
	RebindActive bool
	// RequireKeyAbsent makes Finalize fail atomically with ErrAlreadyExists
	// when Key already has an active mapping. Fork uses this compare-and-set
	// guard in addition to its key lease so a stale or non-cooperating writer
	// cannot create two active children for the same host key.
	RequireKeyAbsent bool
}

FinalizeRequest tells a Store how to persist the post-run thread state: save the new record, optionally archive the previous one, and rebind the key's active mapping — atomically relative to the store's backend, after validating every held lease. When RequireKeyAbsent is set, checking the key precondition and applying all mutations are one atomic operation.

type Lease ¶

type Lease struct {
	Target string
	Owner  string
	Token  string
}

Lease is the concurrent-use guard returned by Store.AcquireLease. Stores must validate Owner+Token during Finalize, RenewLease, and ReleaseLease so an expired-and-reacquired lease can never finalize stale state.

type LeaseLostError ¶

type LeaseLostError struct {
	Target string
}

LeaseLostError is returned by RenewLease/Finalize when the caller no longer owns the lease (expired, released, or reacquired by someone else). Unwrap returns ErrLeaseLost.

func (e *LeaseLostError) Error() string

func (e *LeaseLostError) Unwrap() error

type Query ¶

type Query struct {
	ID              string
	Key             string
	IncludeArchived bool
}

Query is the lookup shape passed to Store.Resolve. Exactly one of ID or Key is set. Archived records are only returned when IncludeArchived is true.

type Record ¶

type Record struct {
	// ID is the SDK-assigned internal session identifier. Consumers use the
	// thread key and run IDs; stores index by ID and keep it stable for the
	// record's lifetime.
	ID string
	// Key is the host's thread key — the stable business handle. Multiple
	// records may share a Key over time when a resume fallback archives the
	// old one; at most one of them is StatusActive. Fork requires a previously
	// unused target key and never archives its parent.
	Key string
	// Status is the lifecycle state (active / archived).
	Status Status
	// DriverType records which driver produced the checkpoint.
	DriverType string
	// Agent is the caller identity captured at persist time.
	Agent driver.AgentIdentity
	// Fingerprint is the invocation fingerprint captured at persist time.
	Fingerprint string
	// CompatibilityFingerprint is the guard compared on resume; a mismatch
	// rejects the resume instead of contaminating the conversation.
	CompatibilityFingerprint string
	// SessionCodec is the stable name of the driver codec that normalized
	// State. Fork and resume coordination use it to reject checkpoint formats
	// that the current driver cannot safely interpret.
	SessionCodec string
	// State is the driver-owned resume checkpoint.
	State *driver.SessionState
	// CreatedAt/UpdatedAt are storage timestamps (UTC).
	CreatedAt time.Time
	UpdatedAt time.Time
}

Record is the durable per-conversation record a Store persists. State is driver-owned checkpoint data; the fingerprint fields are used to reject unsafe resumes when important context (identity, model, workspace, instructions, ...) changed between runs.

type Status ¶

type Status string

Status is the storage lifecycle state of a Record.

const (
	// StatusActive marks the current record for a thread key.
	StatusActive Status = "active"
	// StatusArchived marks a previous record retained for audit/forking.
	StatusArchived Status = "archived"
)

type Store ¶

type Store interface {
	Resolve(ctx context.Context, q Query) (*Record, error)
	Finalize(ctx context.Context, req FinalizeRequest) error
	AcquireLease(ctx context.Context, target, owner string, ttl time.Duration) (Lease, error)
	RenewLease(ctx context.Context, lease Lease, ttl time.Duration) error
	ReleaseLease(ctx context.Context, lease Lease) error
}

Store persists Thread state for resume-capable Drivers:

• Resolve: look up by internal ID or by thread key. A missing record is (nil, nil), not an error. Archived records require IncludeArchived.
• Finalize: validate every held lease (owner+token, unexpired), then atomically save/archive/rebind.
• AcquireLease / RenewLease / ReleaseLease: exclusive-use coordination. Acquire fails with a BusyError while another owner holds an unexpired lease on target; acquiring an expired or self-owned lease succeeds. Context and backend failures retain their original errors.Is identity and must not be reported as BusyError. Renew and Finalize fail with a LeaseLostError when the caller no longer owns the matching token. Release is idempotent and ignores lost/stale leases.