Documentation
¶
Overview ¶
Package filesystem is a single-process reference implementation of agentkit.HistoryStore backed by one JSON file per History version. Each Process gets its own {dir}/{pid}/ directory, and each version a {dir}/{pid}/{ref}.json written atomically via temp-file + fsync + rename + directory fsync (the rename is the commit point), mirroring the discipline in repository/filesystem.
Versions are immutable, as the port requires: Save mints a fresh ref and writes a new file, never touching one it handed out earlier. Refs are UUIDv7, so the directory listing reads in creation order. Discard removes the file.
Constraints (stated honestly): it is single-process only — a LOCK file (flock) makes a second New on the same directory fail — and there is no snapshot to reload, so every Load reads its file directly. It suits development, tests, and small one-shot runs. It has no reclamation policy of its own beyond Discard, so versions left behind by a crash between a save and its commit stay on disk until someone removes them.
Index ¶
- Variables
- type Store
- func (s *Store) Close() error
- func (s *Store) Discard(ctx context.Context, pid agentkit.ProcessID, ref agentkit.HistoryRef)
- func (s *Store) Load(ctx context.Context, pid agentkit.ProcessID, ref agentkit.HistoryRef) (*gollem.History, error)
- func (s *Store) Save(ctx context.Context, pid agentkit.ProcessID, h *gollem.History) (agentkit.HistoryRef, error)
Constants ¶
This section is empty.
Variables ¶
var ErrInvalidPathComponent = goerr.New("invalid path component")
ErrInvalidPathComponent is returned when a ProcessID or HistoryRef is unsafe to use as a path element (empty, or containing a path separator or "..").
Functions ¶
This section is empty.
Types ¶
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store is the filesystem-backed agentkit.HistoryStore.
func New ¶
New opens (or creates) a filesystem Store rooted at dir. It acquires an exclusive flock on {dir}/LOCK; a second concurrent New on the same directory fails.
func (*Store) Close ¶
Close releases the flock. After Close the Store must not be used; reopening with New on the same directory is safe (each version lives in its own file, so there is no snapshot to reload).
func (*Store) Discard ¶
Discard removes the version's file. An unknown ref, an already-discarded one, and an unsafe path component are all silent no-ops: Discard is a notification with nothing to report back (agentkit.HistoryStore).
func (*Store) Load ¶
func (s *Store) Load(ctx context.Context, pid agentkit.ProcessID, ref agentkit.HistoryRef) (*gollem.History, error)
Load reads {dir}/{pid}/{ref}.json. A missing file is agentkit.ErrHistoryVersionMissing: the caller referenced a version, so its absence is data loss rather than an empty conversation. Unmarshal errors (including gollem's Version gate) propagate wrapped, not swallowed.
func (*Store) Save ¶
func (s *Store) Save(ctx context.Context, pid agentkit.ProcessID, h *gollem.History) (agentkit.HistoryRef, error)
Save marshals h and writes it to {dir}/{pid}/{ref}.json under a fresh UUIDv7 ref, via temp file -> fsync -> rename -> directory fsync. It never touches a version returned by an earlier Save.
Source Files