david/knox
1
0
Fork 0
Code Issues 1 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

fix: harden gossip, HLC restarts, watcher races, MCP args, pagination (#3)

Browse Source 
Implements the top findings from the codebase review, verified with tests and live CLI/MCP checks.

**Gossip integrity**
- Push validation: 4 MiB body cap, 1000-row batch cap; rows claiming the local node id (vector-poisoning), empty node ids, and negative HCLs rejected (internal/watch/gossip.go, internal/db/gossip.go)
- Reconcile-on-pull: Run returns the pulled count, syncGossip rebuilds derived state when > 0 — entry-count comparison could never fire, so synced observations never materialized into searchable entries

**Data-layer safety**
- HLC resumed from MAX(hcl) at Open (hlc.SeekTo): a restart with a regressed wall clock cannot reissue values the (node_id, hcl) locator and pull cursors depend on
- Writer serialization: _txlock=immediate DSN + SetMaxOpenConns(1) + per-KnoxDB mutex around RecordObservation's check-then-insert dedup (closes duplicate-row race)

**Watch daemon**
- Ticker guard flags now atomic.Bool (was a cross-goroutine data race)
- Trailing-edge per-path debounce (timer-based, pruned on fire/delete)
- Recursive watches (startup tree walk + watcher.Add on dir Create); Rename re-ingests, Remove cancels pending ingests

**MCP + CLI**
- Strict arg validation, no silent clamping: thread_id 0 errors instead of renaming thread #1; empty knox_thread_link {} errors instead of false success; thread existence checked before writes; golden-thread tool nil-safe
- --page 0 errors instead of panicking; query/recent pagination actually pages (page x limit)

**Tests** (new internal/hlc and internal/db packages): SeekTo monotonicity, concurrent dedup race, push validation, reopen HCL monotonicity, batch caps, self-spoof rejection, idempotency on observation counts.

Verified: go build, go vet, full suite with -race, live MCP stdio transcripts against a scratch DB.
Reviewed-on: #3
Co-authored-by: David Gwilliam <dhgwilliam@gmail.com>
Co-committed-by: David Gwilliam <dhgwilliam@gmail.com>
This commit was merged in pull request #3.
This commit is contained in:
David Gwilliam
2026-09-17 09:06:08 +00:00
committed by david
parent d6d2a24ddc
commit bb852faa27
10 changed files with 733 additions and 116 deletions
Download Patch File Download Diff File Expand all files Collapse all files
internal/cmd/mcp.go
+180 -40
View File
@@ -4,6 +4,7 @@ import (
"context"
"encoding/json"
"fmt"
"math"
"strings"
"github.com/david/knox/internal/db"
@@ -50,8 +51,14 @@ func NewMCPServer(kdb *db.KnoxDB) *server.MCPServer {
)
s.AddTool(searchTool, func(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
query, _ := req.Params.Arguments["query"].(string)
limit := clampInt(req, "limit", 10, 1, 50)
query, err := requiredStringArg(req, "query")
if err != nil {
return errorResult(err.Error()), nil
}
limit, err := optionalIntArg(req, "limit", 10, 1, 50)
if err != nil {
return errorResult(err.Error()), nil
}
detail := parseDetail(getString(req, "detail", "normal"))
scope := getString(req, "scope", "all")
@@ -76,7 +83,10 @@ func NewMCPServer(kdb *db.KnoxDB) *server.MCPServer {
)
s.AddTool(recentTool, func(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
limit := clampInt(req, "limit", 10, 1, 50)
limit, err := optionalIntArg(req, "limit", 10, 1, 50)
if err != nil {
return errorResult(err.Error()), nil
}
detail := parseDetail(getString(req, "detail", "normal"))
scope := getString(req, "scope", "all")
@@ -99,7 +109,10 @@ func NewMCPServer(kdb *db.KnoxDB) *server.MCPServer {
)
s.AddTool(getTool, func(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
fp := getString(req, "fingerprint", "")
fp, err := requiredStringArg(req, "fingerprint")
if err != nil {
return errorResult(err.Error()), nil
}
entry, err := kdb.FindEntry(fp)
if err != nil {
@@ -165,7 +178,10 @@ func NewMCPServer(kdb *db.KnoxDB) *server.MCPServer {
)
s.AddTool(countTool, func(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
query, _ := req.Params.Arguments["query"].(string)
query, err := requiredStringArg(req, "query")
if err != nil {
return errorResult(err.Error()), nil
}
results, err := kdb.Search(query, 500)
if err != nil {
return errorResult(err.Error()), nil
@@ -235,7 +251,10 @@ func NewMCPServer(kdb *db.KnoxDB) *server.MCPServer {
)
s.AddTool(threadCreateTool, func(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
title := getString(req, "title", "")
title, err := requiredStringArg(req, "title")
if err != nil {
return errorResult(err.Error()), nil
}
motivation := getString(req, "motivation", "")
priority := getString(req, "priority", "medium")
provenance := getString(req, "provenance", "{}")
@@ -257,7 +276,10 @@ func NewMCPServer(kdb *db.KnoxDB) *server.MCPServer {
)
s.AddTool(threadUpdateTool, func(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
id := int64(clampInt(req, "thread_id", 0, 1, 999999))
id, err := requiredIntArg(req, "thread_id", 1, 999999)
if err != nil {
return errorResult(err.Error()), nil
}
title := getString(req, "title", "")
motivation := getString(req, "motivation", "")
priority := getString(req, "priority", "")
@@ -281,7 +303,10 @@ func NewMCPServer(kdb *db.KnoxDB) *server.MCPServer {
)
s.AddTool(threadDraftTool, func(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
limit := clampInt(req, "limit", 20, 1, 200)
limit, err := optionalIntArg(req, "limit", 20, 1, 200)
if err != nil {
return errorResult(err.Error()), nil
}
threads, err := kdb.ListThreads("")
if err != nil {
return errorResult(err.Error()), nil
@@ -329,9 +354,18 @@ func NewMCPServer(kdb *db.KnoxDB) *server.MCPServer {
)
s.AddTool(threadLinkTool, func(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
threadID := int64(clampInt(req, "thread_id", 0, 1, 999999))
obsID := int64(clampInt(req, "observation_id", 0, 1, 999999))
threadID, err := requiredIntArg(req, "thread_id", 1, 999999)
if err != nil {
return errorResult(err.Error()), nil
}
obsID, err := requiredIntArg(req, "observation_id", 1, 999999)
if err != nil {
return errorResult(err.Error()), nil
}
relevance := getString(req, "relevance", "")
if err := threadExists(kdb, threadID); err != nil {
return errorResult(err.Error()), nil
}
if err := kdb.LinkObservationToThread(threadID, obsID, relevance); err != nil {
return errorResult(err.Error()), nil
}
@@ -345,7 +379,10 @@ func NewMCPServer(kdb *db.KnoxDB) *server.MCPServer {
)
s.AddTool(threadSearchTool, func(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
query := getString(req, "query", "")
query, err := requiredStringArg(req, "query")
if err != nil {
return errorResult(err.Error()), nil
}
threads, err := kdb.SearchThreadsByMotivation(query)
if err != nil {
return errorResult(err.Error()), nil
@@ -372,9 +409,18 @@ func NewMCPServer(kdb *db.KnoxDB) *server.MCPServer {
)
s.AddTool(threadLinkEntryTool, func(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
threadID := int64(clampInt(req, "thread_id", 0, 1, 999999))
fp := getString(req, "fingerprint", "")
threadID, err := requiredIntArg(req, "thread_id", 1, 999999)
if err != nil {
return errorResult(err.Error()), nil
}
fp, err := requiredStringArg(req, "fingerprint")
if err != nil {
return errorResult(err.Error()), nil
}
relation := getString(req, "relation", "produced")
if err := threadExists(kdb, threadID); err != nil {
return errorResult(err.Error()), nil
}
if err := kdb.LinkEntryToThread(threadID, fp, relation); err != nil {
return errorResult(err.Error()), nil
}
@@ -390,9 +436,21 @@ func NewMCPServer(kdb *db.KnoxDB) *server.MCPServer {
)
s.AddTool(threadRelateTool, func(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
parentID := int64(clampInt(req, "parent_id", 0, 1, 999999))
childID := int64(clampInt(req, "child_id", 0, 1, 999999))
parentID, err := requiredIntArg(req, "parent_id", 1, 999999)
if err != nil {
return errorResult(err.Error()), nil
}
childID, err := requiredIntArg(req, "child_id", 1, 999999)
if err != nil {
return errorResult(err.Error()), nil
}
relation := getString(req, "relation", "spawned")
if err := threadExists(kdb, parentID); err != nil {
return errorResult(err.Error()), nil
}
if err := threadExists(kdb, childID); err != nil {
return errorResult(err.Error()), nil
}
if err := kdb.LinkEntryToThread(childID, db.ThreadFP(parentID), relation); err != nil {
return errorResult(err.Error()), nil
}
@@ -406,29 +464,67 @@ func NewMCPServer(kdb *db.KnoxDB) *server.MCPServer {
)
s.AddTool(goldenTool, func(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
threadID := int64(clampInt(req, "thread_id", 0, 0, 999999))
if threadID == 0 {
// Query or clear
current, _ := kdb.GoldenThreadID()
// Absent thread_id: query the current golden thread.
if _, ok := req.Params.Arguments["thread_id"]; !ok {
current, err := kdb.GoldenThreadID()
if err != nil {
return errorResult(err.Error()), nil
}
if current == 0 {
return mcp.NewToolResultText("No golden thread set."), nil
}
// If thread_id was explicitly 0 and a golden exists, clear it
if _, ok := req.Params.Arguments["thread_id"]; ok {
kdb.SetGoldenThread(0)
t, _ := kdb.GetThread(current)
return mcp.NewToolResultText(fmt.Sprintf("Golden thread cleared (was #%d: %s)", current, t.Title)), nil
t, err := kdb.GetThread(current)
if err != nil {
return errorResult(err.Error()), nil
}
if t == nil {
return errorResult(fmt.Sprintf("Golden thread #%d no longer exists", current)), nil
}
t, _ := kdb.GetThread(current)
return mcp.NewToolResultText(fmt.Sprintf("Golden thread: #%d %s [%s]\n %s", t.ID, t.Title, t.Status, t.Motivation)), nil
}
threadID, err := requiredIntArg(req, "thread_id", 0, 999999)
if err != nil {
return errorResult(err.Error()), nil
}
if threadID == 0 {
// Explicit 0 clears the golden thread.
current, err := kdb.GoldenThreadID()
if err != nil {
return errorResult(err.Error()), nil
}
if current == 0 {
return mcp.NewToolResultText("No golden thread set."), nil
}
if err := kdb.SetGoldenThread(0); err != nil {
return errorResult(err.Error()), nil
}
t, err := kdb.GetThread(current)
if err != nil {
return errorResult(err.Error()), nil
}
name := "?"
if t != nil {
name = t.Title
}
return mcp.NewToolResultText(fmt.Sprintf("Golden thread cleared (was #%d: %s)", current, name)), nil
}
if err := threadExists(kdb, threadID); err != nil {
return errorResult(err.Error()), nil
}
if err := kdb.SetGoldenThread(threadID); err != nil {
return errorResult(err.Error()), nil
}
t, _ := kdb.GetThread(threadID)
return mcp.NewToolResultText(fmt.Sprintf("Golden thread set to #%d: %s", threadID, t.Title)), nil
t, err := kdb.GetThread(threadID)
if err != nil {
return errorResult(err.Error()), nil
}
name := "?"
if t != nil {
name = t.Title
}
return mcp.NewToolResultText(fmt.Sprintf("Golden thread set to #%d: %s", threadID, name)), nil
})
// ─── knox_topics ───────────────────────────────────────────
@@ -438,7 +534,10 @@ func NewMCPServer(kdb *db.KnoxDB) *server.MCPServer {
)
s.AddTool(topicsTool, func(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
limit := clampInt(req, "limit", 10, 1, 30)
limit, err := optionalIntArg(req, "limit", 10, 1, 30)
if err != nil {
return errorResult(err.Error()), nil
}
entries, _ := kdb.RecentEntries(2000)
tfidf := index.BuildTFIDF(entries)
clusters := tfidf.Cluster(2, limit)
@@ -618,18 +717,59 @@ func getString(req mcp.CallToolRequest, key, def string) string {
return def
}
func clampInt(req mcp.CallToolRequest, key string, def, min, max int) int {
if v, ok := req.Params.Arguments[key].(float64); ok {
n := int(v)
if n < min {
return min
}
if n > max {
return max
}
return n
// requiredStringArg returns a non-empty string argument or a descriptive error.
// Empty/missing/wrong-type values are rejected rather than silently defaulted:
// LLM clients routinely omit or zero value params, and a silent default writes
// to the wrong thread or reports false success.
func requiredStringArg(req mcp.CallToolRequest, key string) (string, error) {
v, _ := req.Params.Arguments[key].(string)
v = strings.TrimSpace(v)
if v == "" {
return "", fmt.Errorf("%s is required and must be a non-empty string", key)
}
return def
return v, nil
}
// requiredIntArg returns an integer argument validated against [min, max].
func requiredIntArg(req mcp.CallToolRequest, key string, min, max int64) (int64, error) {
v, ok := req.Params.Arguments[key].(float64)
if !ok || v != math.Trunc(v) {
return 0, fmt.Errorf("%s is required and must be an integer", key)
}
n := int64(v)
if n < min || n > max {
return 0, fmt.Errorf("%s must be in [%d..%d], got %d", key, min, max, n)
}
return n, nil
}
// optionalIntArg validates a present numeric argument, defaulting when absent.
func optionalIntArg(req mcp.CallToolRequest, key string, def, min, max int) (int, error) {
v, ok := req.Params.Arguments[key].(float64)
if !ok {
return def, nil
}
if v != math.Trunc(v) {
return 0, fmt.Errorf("%s must be an integer", key)
}
n := int(v)
if n < min || n > max {
return 0, fmt.Errorf("%s must be in [%d..%d], got %d", key, min, max, n)
}
return n, nil
}
// threadExists is a guard for write tools: link/relate/set-golden must not
// silently accept ids with no matching thread.
func threadExists(kdb *db.KnoxDB, id int64) error {
t, err := kdb.GetThread(id)
if err != nil {
return err
}
if t == nil {
return fmt.Errorf("thread #%d not found", id)
}
return nil
}
func shortFP(fp string) string {
internal/cmd/status.go
+19 -6
View File
@@ -13,7 +13,7 @@ import (
func paginate(entries []db.Entry, page, limit int) []db.Entry {
start := (page - 1) * limit
if start >= len(entries) {
if start < 0 || start >= len(entries) {
return nil
}
end := start + limit
@@ -74,16 +74,22 @@ func NewQueryCmd(kdb *db.KnoxDB) *cobra.Command {
if query == "" {
return fmt.Errorf("search query required (positional arg or stdin pipe)")
}
results, err := kdb.Search(query, limit)
if page < 1 || limit < 1 {
return fmt.Errorf("page and limit must be >= 1 (got page=%d limit=%d)", page, limit)
}
// Fetch enough rows to cover the requested page: Search caps at its
// limit argument, so slicing a limit-sized result set could never
// reach page 2+.
all, err := kdb.Search(query, page*limit)
if err != nil {
return err
}
results = paginate(results, page, limit)
results := paginate(all, page, limit)
if len(results) == 0 {
fmt.Println("No results found.")
return nil
}
fmt.Printf("Found %d results for %q (page %d, %d per page):\n\n", len(results), query, page, limit)
fmt.Printf("Found %d results for %q — showing %d (page %d, %d per page):\n\n", len(all), query, len(results), page, limit)
for _, r := range results {
fmt.Printf(" %-8s %-30s [%s] %s\n", shortFP(r.Fingerprint), truncateStr(r.Title, 30), r.Project, r.SourceID)
if r.Summary != "" {
@@ -105,13 +111,20 @@ func NewRecentCmd(kdb *db.KnoxDB) *cobra.Command {
Use: "recent",
Short: "Show recent knowledge entries",
RunE: func(c *cobra.Command, args []string) error {
all, err := kdb.RecentEntries(limit * 10)
if page < 1 || limit < 1 {
return fmt.Errorf("page and limit must be >= 1 (got page=%d limit=%d)", page, limit)
}
all, err := kdb.RecentEntries(page * limit)
if err != nil {
return err
}
entries := paginate(all, page, limit)
if len(entries) == 0 {
fmt.Println("No entries yet. Run `knox watch` to start ingesting.")
if page > 1 {
fmt.Printf("No more entries on page %d (page %d of %d).\n", page, page, (len(all)+limit-1)/limit)
} else {
fmt.Println("No entries yet. Run `knox watch` to start ingesting.")
}
return nil
}
fmt.Printf("Recent %d entries (page %d, %d per page):\n\n", len(entries), page, limit)