refactor(store): tighten AX doc comments

Co-Authored-By: Virgil <virgil@lethean.io>

compact.go

@@ -11,7 +11,6 @@ import (
 
 var defaultArchiveOutputDirectory = ".core/archive"
 
-// CompactOptions controls cold archive generation.
 // Usage example: `options := store.CompactOptions{Before: time.Now().Add(-90 * 24 * time.Hour), Output: "/tmp/archive", Format: "gzip"}`
 type CompactOptions struct {
 	Before time.Time
@@ -28,7 +27,6 @@ type compactArchiveEntry struct {
 	committedAtUnixMilli int64
 }
 
-// Compact archives old journal entries as newline-delimited JSON.
 // Usage example: `result := storeInstance.Compact(store.CompactOptions{Before: time.Now().Add(-30 * 24 * time.Hour), Output: "/tmp/archive", Format: "gzip"})`
 func (storeInstance *Store) Compact(options CompactOptions) core.Result {
 	if err := ensureJournalSchema(storeInstance.database); err != nil {

events.go

@@ -7,7 +7,6 @@ import (
 	"time"
 )
 
-// EventType identifies the kind of mutation emitted by Store.
 // Usage example: `if event.Type == store.EventSet { return }`
 type EventType int
 
@@ -34,7 +33,6 @@ func (t EventType) String() string {
 	}
 }
 
-// Event describes one mutation delivered to watchers and callbacks.
 // Usage example: `event := store.Event{Type: store.EventSet, Group: "config", Key: "colour", Value: "blue"}`
 // Usage example: `event := store.Event{Type: store.EventDeleteGroup, Group: "config"}`
 type Event struct {
@@ -61,7 +59,6 @@ type changeCallbackRegistration struct {
 // dropping new ones.
 const watcherEventBufferCapacity = 16
 
-// Watch registers a buffered subscription for one group.
 // Usage example: `events := storeInstance.Watch("config")`
 // Usage example: `events := storeInstance.Watch("*")`
 func (storeInstance *Store) Watch(group string) <-chan Event {
@@ -77,7 +74,6 @@ func (storeInstance *Store) Watch(group string) <-chan Event {
 	return eventChannel
 }
 
-// Unwatch removes a watcher for one group and closes its event stream.
 // Usage example: `storeInstance.Unwatch("config", events)`
 func (storeInstance *Store) Unwatch(group string, events <-chan Event) {
 	if events == nil {
@@ -115,7 +111,6 @@ func (storeInstance *Store) Unwatch(group string, events <-chan Event) {
 	storeInstance.watchers[group] = nextRegisteredEvents
 }
 
-// OnChange registers a synchronous mutation callback.
 // Usage example: `unregister := storeInstance.OnChange(func(event store.Event) { fmt.Println(event.Group, event.Key, event.Value) })`
 func (storeInstance *Store) OnChange(callback func(Event)) func() {
 	if callback == nil {

journal.go

@@ -36,7 +36,6 @@ type journalExecutor interface {
 	Exec(query string, args ...any) (sql.Result, error)
 }
 
-// CommitToJournal records one completed unit of work in the store journal.
 // Usage example: `result := storeInstance.CommitToJournal("scroll-session", map[string]any{"like": 4}, map[string]string{"workspace": "scroll-session"})`
 func (storeInstance *Store) CommitToJournal(measurement string, fields map[string]any, tags map[string]string) core.Result {
 	if measurement == "" {
@@ -85,8 +84,6 @@ func (storeInstance *Store) CommitToJournal(measurement string, fields map[strin
 	}
 }
 
-// QueryJournal reads journal rows either through a small Flux-like filter
-// surface or a direct SQL SELECT against the internal journal table.
 // Usage example: `result := storeInstance.QueryJournal(\`from(bucket: "store") |> range(start: -24h)\`)`
 func (storeInstance *Store) QueryJournal(flux string) core.Result {
 	if err := ensureJournalSchema(storeInstance.database); err != nil {

scope.go

@@ -13,7 +13,6 @@ var validNamespace = regexp.MustCompile(`^[a-zA-Z0-9-]+$`)
 
 const defaultScopedGroupName = "default"
 
-// QuotaConfig sets per-namespace key and group limits.
 // Usage example: `quota := store.QuotaConfig{MaxKeys: 100, MaxGroups: 10}`
 type QuotaConfig struct {
 	// Usage example: `store.QuotaConfig{MaxKeys: 100, MaxGroups: 10}` limits a namespace to 100 keys.
@@ -30,7 +29,6 @@ type ScopedStore struct {
 	MaxGroups int
 }
 
-// NewScoped validates a namespace and prefixes groups with namespace + ":".
 // Usage example: `scopedStore := store.NewScoped(storeInstance, "tenant-a")`
 func NewScoped(storeInstance *Store, namespace string) *ScopedStore {
 	if storeInstance == nil {
@@ -43,7 +41,6 @@ func NewScoped(storeInstance *Store, namespace string) *ScopedStore {
 	return scopedStore
 }
 
-// NewScopedWithQuota adds per-namespace key and group limits.
 // Usage example: `scopedStore, err := store.NewScopedWithQuota(storeInstance, "tenant-a", store.QuotaConfig{MaxKeys: 100, MaxGroups: 10}); if err != nil { return }`
 func NewScopedWithQuota(storeInstance *Store, namespace string, quota QuotaConfig) (*ScopedStore, error) {
 	scopedStore := NewScoped(storeInstance, namespace)
@@ -77,7 +74,6 @@ func (scopedStore *ScopedStore) trimNamespacePrefix(groupName string) string {
 	return core.TrimPrefix(groupName, scopedStore.namespacePrefix())
 }
 
-// Namespace returns the namespace string.
 // Usage example: `scopedStore := store.NewScoped(storeInstance, "tenant-a"); if scopedStore == nil { return }; namespace := scopedStore.Namespace(); fmt.Println(namespace)`
 func (scopedStore *ScopedStore) Namespace() string {
 	return scopedStore.namespace

store.go

@@ -38,7 +38,6 @@ type journalConfiguration struct {
 	bucketName   string
 }
 
-// JournalConfiguration is the public snapshot returned by Store.JournalConfiguration().
 // Usage example: `config := storeInstance.JournalConfiguration(); fmt.Println(config.EndpointURL, config.Organisation, config.BucketName)`
 type JournalConfiguration struct {
 	// Usage example: `config := store.JournalConfiguration{EndpointURL: "http://127.0.0.1:8086"}`
@@ -255,7 +254,6 @@ func (storeInstance *Store) DeleteGroup(group string) error {
 	return nil
 }
 
-// KeyValue is one item returned by All.
 // Usage example: `for entry, err := range storeInstance.All("config") { if err != nil { break }; fmt.Println(entry.Key, entry.Value) }`
 type KeyValue struct {
 	// Usage example: `if entry.Key == "colour" { return }`

workspace.go

@@ -44,7 +44,6 @@ type Workspace struct {
 	closed    bool
 }
 
-// NewWorkspace creates a workspace state file under `.core/state/`.
 // Usage example: `workspace, err := storeInstance.NewWorkspace("scroll-session-2026-03-30")`
 func (storeInstance *Store) NewWorkspace(name string) (*Workspace, error) {
 	validation := core.ValidateName(name)
@@ -138,7 +137,6 @@ func (storeInstance *Store) cleanUpOrphanedWorkspaces(stateDirectory string) {
 	}
 }
 
-// Put appends one entry to the workspace buffer.
 // Usage example: `err := workspace.Put("like", map[string]any{"user": "@alice", "post": "video_123"})`
 func (workspace *Workspace) Put(kind string, data map[string]any) error {
 	if kind == "" {
@@ -165,7 +163,6 @@ func (workspace *Workspace) Put(kind string, data map[string]any) error {
 	return nil
 }
 
-// Aggregate returns the current per-kind entry counts in the workspace.
 // Usage example: `summary := workspace.Aggregate()`
 func (workspace *Workspace) Aggregate() map[string]any {
 	fields, err := workspace.aggregateFields()
@@ -192,13 +189,11 @@ func (workspace *Workspace) Commit() core.Result {
 	return core.Result{Value: fields, OK: true}
 }
 
-// Discard closes the workspace and removes its backing file.
 // Usage example: `workspace.Discard()`
 func (workspace *Workspace) Discard() {
 	_ = workspace.closeAndDelete()
 }
 
-// Query runs ad-hoc SQL against the workspace buffer.
 // Usage example: `result := workspace.Query("SELECT entry_kind, COUNT(*) AS count FROM workspace_entries GROUP BY entry_kind")`
 func (workspace *Workspace) Query(sqlQuery string) core.Result {
 	rows, err := workspace.database.Query(sqlQuery)