overlay

Documentation

Overview

Package overlay implements stoa's read path.

A read never returns canonical content alone. It returns canonical PLUS the journal entries that target it and have not been consolidated yet, clearly marked as pending. That is the whole reason consolidation latency is harmless: information is visible the moment it is written, and only tidiness waits for the consolidator.

Index

• type Hit
  • func Search(s *store.Store, term string, caseSensitive bool) ([]Hit, error)
• type Note
• type Result
  • func Read(s *store.Store, target string) (*Result, error)
• type Task
  • func Tasks(s *store.Store) ([]Task, error)
  • func (t Task) Lapsed(now time.Time) bool

Types

type Hit

type Hit struct {
	Path    string
	Line    int
	Text    string
	Pending bool           // true when the match came from an unconsolidated entry
	Entry   *journal.Entry // set when Pending
}

Hit is one search match.

func Search

func Search(s *store.Store, term string, caseSensitive bool) ([]Hit, error)

Search greps canonical notes and journal entries for a term, marking journal matches as pending so a reader can tell settled knowledge from fresh entries.

type Note

type Note struct {
	Path    string // store-relative
	Content string
	Exists  bool
}

Note is one canonical note's content.

type Result

type Result struct {
	Notes   []Note
	Pending []journal.Entry
}

Result is a read: the canonical notes asked for, plus pending entries.

func Read

func Read(s *store.Store, target string) (*Result, error)

Read resolves target -- a note path, a domain directory, or a not-yet-created note -- and returns canonical content with the pending overlay.

Pending entries for targets that do not exist yet are included on purpose: a fact written about a note nobody has created must still be readable, or the store would swallow new information until someone consolidated it.

type Task

type Task struct {
	Key      string
	Holder   string          // "" when nobody currently has dibs
	Since    string          // RFC3339 stamp of the winning dibs
	Yielded  []journal.Entry // later callers that lost the race
	Released bool            // a RELEASE or DONE arrived for the winning dibs
	Done     bool

	// LeaseEnds is when the current holder's dibs lapse. Zero when the task is
	// not held. Renewing pushes it out; it is measured from the holder's most
	// recent call, not from when they first took the task.
	LeaseEnds time.Time

	// TookOverFrom and TookOverAt record that the current holder took the task
	// from a previous holder whose lease had lapsed. Kept because a silent
	// takeover reads as "this was always mine" to everyone downstream.
	TookOverFrom string
	TookOverAt   string
}

Task is the resolved state of one task key.

Nothing here is enforcement. Holder is who called dibs first, not who has been granted exclusive access -- there is no such grant anywhere in stoa. Every member remains free to write whatever they like at any time; dibs only tells them who got there first, so that honouring it is possible.

func Tasks

func Tasks(s *store.Store) ([]Task, error)

Tasks resolves who has dibs on what, from journal entries alone.

The race is decided by one rule with no human in it: among live dibs on a task, the earliest timestamp wins and every later caller yields. Two agents that call the same task inside the sync window therefore reach the same answer independently, as soon as they can see each other's journals.

Dibs lapse. If a later call arrives more than one lease after the holder's most recent one, the caller takes the task over instead of yielding, so a member who leaves cannot block a task name forever. The comparison is between two entry timestamps rather than against the current time, which is what keeps this a pure function of journal content: every machine resolves the same store identically, whenever it happens to look.

Open dibs are always readable here because the consolidator leaves the entry pending until its RELEASE or DONE arrives -- so a called task never disappears from the read path while the work is still open.

func (Task) Lapsed

func (t Task) Lapsed(now time.Time) bool

Lapsed reports whether the holder's lease has run out as of now.

This is a presentation question, not a resolution one: a lapsed task still reports its holder, because showing it as free would erase the only clue that somebody was working on it. Resolution never consults the wall clock (see Tasks), so two members disagreeing about "now" can disagree about whether to display a lapse warning, and never about who holds what.