scopelease

package

v1.0.0-rc.2 Latest Latest Go to latest Published: Oct 6, 2026 License: AGPL-3.0, AGPL-3.0-or-later Imports: 16 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/Beamfall/corvint

Links

Open Source Insights

Documentation ¶

Rendered for

Overview ¶

Package scopelease implements bounded local scope leases so several agents sharing one worktree cannot silently edit overlapping files or the same ticket. Lease state is private derived state under .corvint/leases; it is never an input to ranking, learning, evidence, or authority, and it enforces nothing about the edits an agent actually makes.

Index ¶

Constants
Variables
func Acquire(root string, request Request) (Lease, []Conflict, error)
func Directory(root string) string
type Conflict
- func Check(root string, paths []string) ([]Conflict, error)
type Lease
- func Release(root, id, holder string) (Lease, error)
- func Renew(root, id, holder string, ttl time.Duration) (Lease, error)
type Report
- func List(root string) ([]Report, error)
- func Status(root, id string) (Report, error)
type Request

Constants ¶

View Source

const (
	// MaxTTL bounds one acquisition or renewal.
	MaxTTL = 24 * time.Hour
	// StaleLockAge is the age after which a lock file is treated as crashed.
	StaleLockAge = 30 * time.Second
	// LockWait bounds how long a writer waits for the single-writer lock.
	LockWait = 2 * time.Second
)

View Source

const SchemaVersion = 1

SchemaVersion is the on-disk lease document version.

Variables ¶

View Source

var (
	ErrConflict       = errors.New("scopelease: scope conflict")
	ErrNotFound       = errors.New("scopelease: lease not found")
	ErrHolderMismatch = errors.New("scopelease: holder does not hold this lease")
	ErrLockBusy       = errors.New("scopelease: lease lock is held by another writer")
	// ErrInvalidRequest marks a caller-supplied argument refused before any
	// lease state is read; the refusal keeps its own message.
	ErrInvalidRequest = errors.New("scopelease: invalid request")
)

Sentinel errors. Callers use errors.Is.

Functions ¶

func Acquire ¶

func Acquire(root string, request Request) (Lease, []Conflict, error)

Acquire reaps expired leases, refuses on any overlap with a live lease, and otherwise writes one new lease document.

func Directory ¶

func Directory(root string) string

Directory is the private lease directory under root.

Types ¶

type Conflict ¶

type Conflict struct {
	LeaseID string `json:"lease_id"`
	Holder  string `json:"holder"`
	Reason  string `json:"reason"`
	Scope   string `json:"scope"`
}

Conflict explains why a scope could not be claimed, or why a touched path is not covered by exactly one live lease.

func Check ¶

func Check(root string, paths []string) ([]Conflict, error)

Check is a read-only helper for a future CEM or dogfood gate: it reports, for each touched path, whether exactly one live lease covers it. A path that no live lease covers, or that two or more live leases cover, is a conflict. It is wired to nothing else and writes nothing.

type Lease ¶

type Lease struct {
	SchemaVersion int      `json:"schema_version"`
	ID            string   `json:"lease_id"`
	Holder        string   `json:"holder"`
	Paths         []string `json:"paths"`
	Ticket        string   `json:"ticket"`
	Note          string   `json:"note"`
	AcquiredAt    string   `json:"acquired_at"`
	ExpiresAt     string   `json:"expires_at"`
	Revision      string   `json:"revision"`
}

Lease is one recorded local scope claim.

func Release ¶

func Release(root, id, holder string) (Lease, error)

Release reaps expired leases and removes one lease held by holder.

func Renew ¶

func Renew(root, id, holder string, ttl time.Duration) (Lease, error)

Renew reaps expired leases and extends one lease held by holder to now plus ttl, never earlier than its recorded expiry (decision 0254).

type Report ¶

type Report struct {
	Lease Lease  `json:"lease"`
	State string `json:"state"`
}

Report pairs a lease with its reported state: "live" or "expired".

func List ¶

func List(root string) ([]Report, error)

List reports every lease without writing anything, including without reaping. An unreadable document is reported by lease id with state "unreadable".

func Status ¶

func Status(root, id string) (Report, error)

Status reports one lease without writing anything, including without reaping.

type Request ¶

type Request struct {
	Holder string
	Paths  []string
	Ticket string
	Note   string
	TTL    time.Duration
}

Request is one acquisition input.

Source Files ¶

View all Source files

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL