From 79581e9824e4c53dca8b6c7e7953e945c7c77d2a Mon Sep 17 00:00:00 2001 From: Virgil Date: Fri, 3 Apr 2026 07:17:46 +0000 Subject: [PATCH] docs(store): tighten workspace AX comments Align workspace public comments with the AX guidance by using more concrete examples and clearer phrasing. Co-Authored-By: Virgil --- workspace.go | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/workspace.go b/workspace.go index 68fc335..138b414 100644 --- a/workspace.go +++ b/workspace.go @@ -32,7 +32,7 @@ FROM workspace_entries` var defaultWorkspaceStateDirectory = ".core/state" -// Workspace is a named SQLite buffer for mutable work-in-progress. +// Workspace buffers mutable work-in-progress in a temporary SQLite file. // // Usage example: `workspace, err := storeInstance.NewWorkspace("scroll-session-2026-03-30"); if err != nil { return }; defer workspace.Discard()` type Workspace struct { @@ -109,8 +109,8 @@ func (storeInstance *Store) NewWorkspace(name string) (*Workspace, error) { }, nil } -// RecoverOrphans opens leftover workspace files in a state directory so -// callers can inspect them before calling Discard(). +// RecoverOrphans(".core/state") returns orphaned workspaces such as +// `scroll-session.duckdb` so callers can inspect Aggregate() and then Discard(). // Usage example: `orphans := storeInstance.RecoverOrphans(".core/state")` func (storeInstance *Store) RecoverOrphans(stateDirectory string) []*Workspace { if storeInstance == nil { @@ -212,8 +212,8 @@ func (workspace *Workspace) Aggregate() map[string]any { return fields } -// Commit writes the aggregated workspace state to the journal and updates the -// store summary entry for the workspace. +// Commit writes one journal point for the workspace and upserts the summary +// row in `workspace:NAME`. // Usage example: `result := workspace.Commit()` func (workspace *Workspace) Commit() core.Result { if err := workspace.ensureReady("store.Workspace.Commit"); err != nil {