@hybridlabor-api/bdb-synapse 1.0.0

package/internal/server/static/index.html

@@ -0,0 +1,26 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="color-scheme" content="dark" />
+    <meta name="theme-color" content="#12151c" />
+    <link
+      rel="icon"
+      href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 64 64'%3E%3Cdefs%3E%3CradialGradient id='halo'%3E%3Cstop offset='0' stop-color='%23f1aa57' stop-opacity='0.55'/%3E%3Cstop offset='1' stop-color='%23f1aa57' stop-opacity='0'/%3E%3C/radialGradient%3E%3C/defs%3E%3Crect width='64' height='64' rx='14' fill='%230f141b'/%3E%3Ccircle cx='20' cy='15' r='1.6' fill='%233b4047'/%3E%3Ccircle cx='11' cy='27' r='1.4' fill='%233b4047'/%3E%3Ccircle cx='51' cy='40' r='1.6' fill='%233b4047'/%3E%3Ccircle cx='34' cy='53' r='1.4' fill='%233b4047'/%3E%3Cg fill='%23f1aa57'%3E%3Ccircle cx='18.6' cy='47.9' r='1.15' opacity='0.35'/%3E%3Ccircle cx='22.7' cy='45.2' r='1.25' opacity='0.42'/%3E%3Ccircle cx='25.9' cy='42.0' r='1.35' opacity='0.49'/%3E%3Ccircle cx='28.2' cy='38.1' r='1.45' opacity='0.56'/%3E%3Ccircle cx='30.9' cy='29.3' r='1.55' opacity='0.64'/%3E%3Ccircle cx='33.0' cy='25.4' r='1.65' opacity='0.72'/%3E%3Ccircle cx='36.0' cy='22.1' r='1.75' opacity='0.8'/%3E%3Ccircle cx='38.0' cy='20.4' r='1.85' opacity='0.88'/%3E%3C/g%3E%3Ccircle cx='13' cy='50' r='4.5' fill='%239fc67b' opacity='0.16'/%3E%3Ccircle cx='13' cy='50' r='2.4' fill='%239fc67b'/%3E%3Ccircle cx='29.5' cy='34' r='5' fill='%23b6daf1' opacity='0.16'/%3E%3Ccircle cx='29.5' cy='34' r='2.7' fill='%23b6daf1'/%3E%3Ccircle cx='44' cy='17.5' r='9.5' fill='url(%23halo)'/%3E%3Ccircle cx='44' cy='17.5' r='3.4' fill='%23f1aa57'/%3E%3Ccircle cx='44' cy='17.5' r='1.7' fill='%23ffe0b0'/%3E%3C/svg%3E"
+    />
+    <title>mindwalk</title>
+    <style>
+      html {
+        background: #12151c;
+      }
+    </style>
+    <script type="module" crossorigin src="/assets/index-C_adLrJr.js"></script>
+    <link rel="modulepreload" crossorigin href="/assets/react-gcHzaSmV.js">
+    <link rel="modulepreload" crossorigin href="/assets/three-DnGjZfD1.js">
+    <link rel="stylesheet" crossorigin href="/assets/index-BNoY_BiB.css">
+  </head>
+  <body>
+    <div id="root"></div>
+  </body>
+</html>

package/internal/server/tracestore.go

@@ -0,0 +1,173 @@
+package server
+
+import (
+	"fmt"
+	"log"
+	"runtime/debug"
+	"sync"
+	"time"
+
+	"github.com/hybridlabor-api/bdb-synapse/internal/adapter"
+	"github.com/hybridlabor-api/bdb-synapse/internal/model"
+)
+
+// traceStore owns every parsed-session cache behind one lock. It keeps two
+// layers with the same key space (session key) but different value semantics:
+//
+//   - snapshots: the trace projected onto its own citymap (file IDs assigned,
+//     stats recomputed against the repo file count) plus that citymap — what
+//     the session views serve.
+//   - raws: the trace exactly as the adapter parsed it, no projection — what
+//     subagent views load before projecting onto the *root* session's city.
+//
+// Keeping the layers apart means a projected snapshot can never be
+// re-projected and a raw trace can never be served where file IDs are
+// expected. Keys are session keys; the source-file fingerprint is a
+// validation field on the entry — never part of the key — so one session
+// occupies at most one slot per layer.
+type traceStore struct {
+	mu        sync.Mutex
+	snapshots map[string]*traceEntry
+	raws      map[string]*traceEntry
+	inflight  map[string]*inflightLoad
+
+	// Injected by the server: parse-and-project for snapshots, parse-only for
+	// raws. Called without the store lock held.
+	loadSnapshot func(model.SessionMeta) (*model.Trace, *model.CityMap, error)
+	loadRaw      func(model.SessionMeta) (*model.Trace, error)
+}
+
+type traceEntry struct {
+	trace       *model.Trace
+	city        *model.CityMap // nil in the raw layer
+	fingerprint fileFingerprint
+	at          time.Time
+	used        time.Time
+}
+
+type inflightLoad struct {
+	done        chan struct{}
+	fingerprint fileFingerprint
+	trace       *model.Trace
+	city        *model.CityMap
+	err         error
+}
+
+func newTraceStore(loadSnapshot func(model.SessionMeta) (*model.Trace, *model.CityMap, error), loadRaw func(model.SessionMeta) (*model.Trace, error)) *traceStore {
+	return &traceStore{
+		snapshots:    map[string]*traceEntry{},
+		raws:         map[string]*traceEntry{},
+		inflight:     map[string]*inflightLoad{},
+		loadSnapshot: loadSnapshot,
+		loadRaw:      loadRaw,
+	}
+}
+
+func (ts *traceStore) LoadSnapshot(meta model.SessionMeta) (*model.Trace, *model.CityMap, error) {
+	return ts.load(ts.snapshots, "snapshot", meta, ts.loadSnapshot)
+}
+
+func (ts *traceStore) LoadRaw(meta model.SessionMeta) (*model.Trace, error) {
+	trace, _, err := ts.load(ts.raws, "raw", meta, func(meta model.SessionMeta) (*model.Trace, *model.CityMap, error) {
+		trace, err := ts.loadRaw(meta)
+		return trace, nil, err
+	})
+	return trace, err
+}
+
+func (ts *traceStore) load(layer map[string]*traceEntry, kind string, meta model.SessionMeta, loader func(model.SessionMeta) (*model.Trace, *model.CityMap, error)) (*model.Trace, *model.CityMap, error) {
+	key := meta.Key
+	if key == "" {
+		key = adapter.SessionKey(meta.Harness, meta.Path)
+	}
+	inflightKey := kind + "\x00" + key
+	for {
+		fingerprint, err := fingerprintFile(meta.Path)
+		if err != nil {
+			ts.mu.Lock()
+			delete(layer, key)
+			ts.mu.Unlock()
+			return nil, nil, err
+		}
+
+		ts.mu.Lock()
+		if entry := layer[key]; entry != nil {
+			if entry.fingerprint.equal(fingerprint) && time.Since(entry.at) < traceCacheTTL {
+				entry.used = time.Now()
+				trace, city := entry.trace, entry.city
+				ts.mu.Unlock()
+				return trace, city, nil
+			}
+			delete(layer, key)
+		}
+		if load := ts.inflight[inflightKey]; load != nil {
+			done := load.done
+			shareSnapshot := fingerprint.equal(load.fingerprint)
+			ts.mu.Unlock()
+			<-done
+
+			// Requests that observed the same source version must receive the
+			// same trace/city snapshot, even if the active file grows while the
+			// shared parse is running. A request that already observed a newer
+			// version retries after the older load completes.
+			if shareSnapshot {
+				return load.trace, load.city, load.err
+			}
+			continue
+		}
+		load := &inflightLoad{done: make(chan struct{}), fingerprint: fingerprint}
+		ts.inflight[inflightKey] = load
+		ts.mu.Unlock()
+
+		// Keep the pre-parse fingerprint. If the active session grows during
+		// parsing, the next request will see a mismatch and reload it instead
+		// of treating the partial snapshot as current.
+		ts.run(layer, inflightKey, key, load, meta, loader)
+		return load.trace, load.city, load.err
+	}
+}
+
+// run executes the shared load for key and publishes the result on load. The
+// finalize step — cache the result, drop the inflight entry, close load.done
+// — runs in a defer so a panicking loader cannot skip it. Without that,
+// net/http's per-connection recover would swallow the panic while the
+// inflight entry stayed registered, and every later request for the key
+// would block forever on a done channel nothing closes.
+func (ts *traceStore) run(layer map[string]*traceEntry, inflightKey, key string, load *inflightLoad, meta model.SessionMeta, loader func(model.SessionMeta) (*model.Trace, *model.CityMap, error)) {
+	defer func() {
+		if r := recover(); r != nil {
+			load.trace, load.city = nil, nil
+			load.err = fmt.Errorf("load session %s: %v", key, r)
+			log.Printf("mindwalk: panic loading session %s: %v\n%s", key, r, debug.Stack())
+		}
+		ts.mu.Lock()
+		if load.err == nil {
+			now := time.Now()
+			layer[key] = &traceEntry{trace: load.trace, city: load.city, fingerprint: load.fingerprint, at: now, used: now}
+			ts.evictLocked(layer)
+		}
+		delete(ts.inflight, inflightKey)
+		close(load.done)
+		ts.mu.Unlock()
+	}()
+	load.trace, load.city, load.err = loader(meta)
+}
+
+// evictLocked bounds one layer by dropping the least recently used entries
+// once it grows past traceCacheMaxEntries. Caller must hold mu.
+func (ts *traceStore) evictLocked(layer map[string]*traceEntry) {
+	for len(layer) > traceCacheMaxEntries {
+		var oldestKey string
+		var oldest time.Time
+		for key, entry := range layer {
+			if oldestKey == "" || entry.used.Before(oldest) {
+				oldestKey = key
+				oldest = entry.used
+			}
+		}
+		if oldestKey == "" {
+			return
+		}
+		delete(layer, oldestKey)
+	}
+}

package/internal/server/tracestore_test.go

@@ -0,0 +1,51 @@
+package server
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/hybridlabor-api/bdb-synapse/internal/model"
+)
+
+// The raw and snapshot layers share a key space but must never share entries:
+// a session loaded through both APIs is parsed once per layer and each layer
+// serves its own cached value afterwards.
+func TestTraceStoreLayersAreIndependent(t *testing.T) {
+	session := filepath.Join(t.TempDir(), "s.jsonl")
+	if err := os.WriteFile(session, []byte("{}\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	meta := model.SessionMeta{Key: "s", Harness: "test", Path: session}
+
+	snapshotLoads, rawLoads := 0, 0
+	snapshotTrace := &model.Trace{Session: model.TraceSession{ID: "projected"}}
+	rawTrace := &model.Trace{Session: model.TraceSession{ID: "raw"}}
+	city := &model.CityMap{}
+	ts := newTraceStore(
+		func(model.SessionMeta) (*model.Trace, *model.CityMap, error) {
+			snapshotLoads++
+			return snapshotTrace, city, nil
+		},
+		func(model.SessionMeta) (*model.Trace, error) {
+			rawLoads++
+			return rawTrace, nil
+		},
+	)
+
+	for i := 0; i < 2; i++ {
+		trace, gotCity, err := ts.LoadSnapshot(meta)
+		if err != nil || trace != snapshotTrace || gotCity != city {
+			t.Fatalf("snapshot load %d: trace=%v city=%v err=%v", i, trace, gotCity, err)
+		}
+	}
+	for i := 0; i < 2; i++ {
+		trace, err := ts.LoadRaw(meta)
+		if err != nil || trace != rawTrace {
+			t.Fatalf("raw load %d: trace=%v err=%v", i, trace, err)
+		}
+	}
+	if snapshotLoads != 1 || rawLoads != 1 {
+		t.Fatalf("loads = snapshot:%d raw:%d, want 1 each", snapshotLoads, rawLoads)
+	}
+}

package/internal/textutil/truncate.go

@@ -0,0 +1,30 @@
+// Package textutil contains UTF-8-safe helpers shared across trace ingestion
+// and judge rendering.
+package textutil
+
+import "unicode/utf8"
+
+// TruncateRunes limits text to at most limit runes, including marker. Invalid
+// UTF-8 is replaced with the standard replacement rune so callers can safely
+// serialize the result. When the marker itself exceeds the budget, its prefix
+// takes the available space.
+func TruncateRunes(text string, limit int, marker string) string {
+	if limit <= 0 {
+		return ""
+	}
+
+	runes := []rune(text)
+	if len(runes) <= limit {
+		if utf8.ValidString(text) {
+			return text
+		}
+		return string(runes)
+	}
+
+	markerRunes := []rune(marker)
+	if len(markerRunes) > limit {
+		markerRunes = markerRunes[:limit]
+	}
+	contentLimit := limit - len(markerRunes)
+	return string(runes[:contentLimit]) + string(markerRunes)
+}

package/internal/textutil/truncate_test.go

@@ -0,0 +1,39 @@
+package textutil
+
+import (
+	"testing"
+	"unicode/utf8"
+)
+
+func TestTruncateRunes(t *testing.T) {
+	tests := []struct {
+		name   string
+		text   string
+		limit  int
+		marker string
+		want   string
+	}{
+		{name: "unchanged", text: "你好", limit: 2, marker: "...", want: "你好"},
+		{name: "multibyte boundary", text: "aa界tail", limit: 6, marker: "...", want: "aa界..."},
+		{name: "emoji boundary", text: "aa🙂tail", limit: 6, marker: "...", want: "aa🙂..."},
+		{name: "marker within budget", text: "abcdef", limit: 4, marker: "…", want: "abc…"},
+		{name: "marker fills budget", text: "abcdef", limit: 2, marker: "...", want: ".."},
+		{name: "zero budget", text: "abcdef", limit: 0, marker: "…", want: ""},
+		{name: "invalid input", text: string([]byte{'o', 'k', 0xff}), limit: 4, want: "ok�"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := TruncateRunes(tt.text, tt.limit, tt.marker)
+			if got != tt.want {
+				t.Fatalf("TruncateRunes() = %q, want %q", got, tt.want)
+			}
+			if !utf8.ValidString(got) {
+				t.Fatalf("TruncateRunes() returned invalid UTF-8: %q", got)
+			}
+			if gotRunes := len([]rune(got)); gotRunes > tt.limit {
+				t.Fatalf("TruncateRunes() returned %d runes, limit %d", gotRunes, tt.limit)
+			}
+		})
+	}
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@hybridlabor-api/bdb-synapse",
+  "version": "1.0.0",
+  "description": "BDB Synapse — 3D Codebase Visualizer & Agent Session Replay Engine",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hybridlabor-api/bdb-synapse.git"
+  },
+  "keywords": [
+    "bdb",
+    "synapse",
+    "3d",
+    "codebase",
+    "visualization",
+    "agent",
+    "session-replay",
+    "webgl",
+    "threejs"
+  ],
+  "files": [
+    "bin/",
+    "internal/server/static/",
+    "cmd/",
+    "internal/",
+    "web/",
+    "go.mod",
+    "go.sum",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}