From 0ce601483642b23c11db232f632e056943e6fcf9 Mon Sep 17 00:00:00 2001 From: Virgil Date: Fri, 3 Apr 2026 06:20:04 +0000 Subject: [PATCH] docs(store): align agent-facing file layout docs Co-Authored-By: Virgil --- CLAUDE.md | 5 ++++- CODEX.md | 4 +++- docs/architecture.md | 7 +++++-- docs/index.md | 5 ++++- 4 files changed, 16 insertions(+), 5 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 7813518..cb16a2b 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -18,7 +18,7 @@ SQLite key-value store with TTL, namespace isolation, and reactive events. Pure ## Getting Started -Part of the Go workspace at `~/Code/go.work`—run `go work sync` after cloning. Single Go package with `store.go` (core), `events.go` (watchers/callbacks), and `scope.go` (scoping/quota). +Part of the Go workspace at `~/Code/go.work`—run `go work sync` after cloning. Single Go package with `store.go` (core store API), `events.go` (watchers/callbacks), `scope.go` (scoping/quota), `journal.go` (journal persistence/query), `workspace.go` (workspace buffering), and `compact.go` (archive generation). ```bash go test ./... -count=1 @@ -44,6 +44,9 @@ go vet ./... # Vet - `store.go` — Core `Store` type: CRUD on an `entries` table keyed by `(group_name, entry_key)`, TTL via `expires_at` (Unix ms), background purge goroutine (60s interval), `text/template` rendering, `iter.Seq2` iterators - `events.go` — Event system: `Watch`/`Unwatch` (buffered chan, cap 16, non-blocking sends drop events) and `OnChange` callbacks (synchronous in writer goroutine). Watcher and callback registries use separate locks, so callbacks can register or unregister subscriptions without deadlocking. - `scope.go` — `ScopedStore` wraps `*Store`, prefixes groups with `namespace:`. Quota enforcement (`MaxKeys`/`MaxGroups`) checked before writes; upserts bypass quota. Namespace regex: `^[a-zA-Z0-9-]+$` +- `journal.go` — Journal persistence and query helpers layered on SQLite. +- `workspace.go` — Workspace buffers, commit flow, and orphan recovery. +- `compact.go` — Cold archive generation for completed journal entries. **TTL enforcement is triple-layered:** lazy delete on `Get`, query-time `WHERE` filtering on bulk reads, and background purge goroutine. diff --git a/CODEX.md b/CODEX.md index 593747e..1ee757f 100644 --- a/CODEX.md +++ b/CODEX.md @@ -18,5 +18,7 @@ Keep the two files aligned. - `store.go` contains the core store API and SQLite lifecycle. - `events.go` contains mutation events, watchers, and callbacks. - `scope.go` contains namespace isolation and quota enforcement. +- `journal.go` contains journal persistence and query helpers. +- `workspace.go` contains workspace buffering and orphan recovery. +- `compact.go` contains cold archive generation. - `docs/` contains the package docs, architecture notes, and history. - diff --git a/docs/architecture.md b/docs/architecture.md index 7259047..712e26e 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -242,10 +242,13 @@ All operations are safe to call from multiple goroutines concurrently. The race ## File Layout ``` -doc.go Package comment with concrete usage examples +doc.go Package comment with concrete usage examples store.go Core Store type, CRUD, TTL, background purge, iterators, rendering -events.go EventType, Event, Watcher, OnChange, notify +events.go EventType, Event, Watch, Unwatch, OnChange, notify scope.go ScopedStore, QuotaConfig, namespace-local helper delegation, quota enforcement +journal.go Journal persistence, Flux-like querying, JSON row inflation +workspace.go Workspace buffers, aggregation, commit flow, orphan recovery +compact.go Cold archive generation to JSONL gzip or zstd store_test.go Tests: CRUD, TTL, concurrency, edge cases, persistence events_test.go Tests: Watch, Unwatch, OnChange, event dispatch scope_test.go Tests: namespace isolation, quota enforcement diff --git a/docs/index.md b/docs/index.md index ff1466b..f584cb6 100644 --- a/docs/index.md +++ b/docs/index.md @@ -107,7 +107,7 @@ func main() { ## Package Layout -The entire package lives in a single Go package (`package store`) with three implementation files plus `doc.go` for the package comment: +The entire package lives in a single Go package (`package store`) with the following implementation files plus `doc.go` for the package comment: | File | Purpose | |------|---------| @@ -115,6 +115,9 @@ The entire package lives in a single Go package (`package store`) with three imp | `store.go` | Core `Store` type, CRUD operations (`Get`, `Set`, `SetWithTTL`, `Delete`, `DeleteGroup`), bulk queries (`GetAll`, `All`, `Count`, `CountAll`, `Groups`, `GroupsSeq`), string splitting helpers (`GetSplit`, `GetFields`), template rendering (`Render`), TTL expiry, background purge goroutine | | `events.go` | `EventType` constants, `Event` struct, `Watch`/`Unwatch` channel subscriptions, `OnChange` callback registration, internal `notify` dispatch | | `scope.go` | `ScopedStore` wrapper for namespace isolation, `QuotaConfig` struct, `NewScoped`/`NewScopedWithQuota` constructors, namespace-local helper delegation, quota enforcement logic | +| `journal.go` | Journal persistence, Flux-like querying, JSON row inflation, journal schema helpers | +| `workspace.go` | Workspace buffers, aggregation, commit flow, and orphan recovery | +| `compact.go` | Cold archive generation to JSONL gzip or zstd | Tests are organised in corresponding files: