chore(sync): quality-hardening + phase relevance hook and benchmarks

.gitignore

@@ -34,3 +34,4 @@ go.work.sum
 
 # macOS
 .DS_Store
+.gocache/

benchmark/README.md

@@ -0,0 +1,83 @@
+# Yaad Benchmark Publication Workflow
+
+This directory is the publication surface for Yaad benchmarks.
+
+It complements:
+
+- `yaad/internal/bench` for retrieval-quality evaluation
+- `yaad/benchmark/benchmark_test.go` for microbenchmarks
+- `yaad/benchmark/compare.md` for architecture/performance narrative
+- `yaad/benchmark/manifests/` for machine-readable suite definitions
+
+## Official suite ids
+
+- `yaad-longmem-core`
+- `yaad-microbench`
+- `yaad-locomo-beam-publication` (planned)
+
+See the Hawk-side benchmark registry at `hawk/docs/benchmarks/SUITES.md`.
+
+## Current published baselines
+
+- `yaad-longmem-core`: `results/yaad-longmem-core/2026-06-27/`
+- `yaad-microbench`: `results/yaad-microbench/2026-06-27/`
+
+## Current runnable commands
+
+```bash
+/bin/zsh -lc 'GOCACHE=$PWD/.gocache go run ./benchmark/cmd/longmemreport --suite default'
+go test ./benchmark/ -bench=. -benchmem -benchtime=1s
+go test ./benchmark/ -bench=BenchmarkRemember -benchmem
+go test ./benchmark/ -bench=BenchmarkRecall -benchmem
+go test ./benchmark/ -bench=BenchmarkGraphBFS -benchmem
+/bin/zsh -lc 'GOCACHE=$PWD/.gocache go test ./internal/bench -count=1'
+```
+
+## Publication layout
+
+Recommended committed layout:
+
+```text
+benchmark/
+  README.md
+  compare.md
+  results/
+    yaad-longmem-core/
+      2026-06-27/
+        report.md
+        result.txt
+        notes.md
+    yaad-microbench/
+      2026-06-27/
+        report.md
+        result.txt
+        notes.md
+```
+
+## Required metrics
+
+### `yaad-longmem-core`
+
+- R@1
+- R@3
+- R@5
+- R@10
+- MRR
+- avg tokens/query
+- duration
+
+### `yaad-microbench`
+
+- latency
+- allocs/op
+- bytes/op where emitted
+- benchmark environment notes
+
+## Promotion rule
+
+Do not cite a Yaad benchmark as evidence in cross-project comparison docs unless:
+
+1. the command used is recorded
+2. the commit is recorded
+3. the metric table is committed or linked as an artifact
+4. the benchmark scope is stated clearly

benchmark/cmd/longmemreport/main.go

@@ -0,0 +1,100 @@
+package main
+
+import (
+	"context"
+	"flag"
+	"fmt"
+	"os"
+	"path/filepath"
+	"time"
+
+	"github.com/GrayCodeAI/yaad/engine"
+	"github.com/GrayCodeAI/yaad/graph"
+	bench "github.com/GrayCodeAI/yaad/internal/bench"
+	"github.com/GrayCodeAI/yaad/storage"
+)
+
+func main() {
+	var (
+		depth = flag.Int("depth", 2, "recall depth")
+		limit = flag.Int("limit", 10, "recall limit")
+		suite = flag.String("suite", "default", "benchmark suite: default|coding")
+	)
+	flag.Parse()
+
+	ctx := context.Background()
+	dir := mustTempDir()
+	dbPath := filepath.Join(dir, "longmem-core.db")
+
+	store, err := storage.NewStore(dbPath)
+	must(err)
+	defer store.Close() //nolint:errcheck
+
+	eng := engine.New(store, graph.New(store, store.DB()))
+	defer eng.Close()
+
+	must(seedBaseline(ctx, eng))
+
+	var qas []bench.QA
+	switch *suite {
+	case "coding":
+		qas = bench.CodingBenchQAs()
+	default:
+		qas = bench.DefaultQAs()
+	}
+
+	result := bench.Run(ctx, eng, qas, *depth, *limit)
+	fmt.Printf("Suite: yaad-longmem-core (%s)\n", *suite)
+	fmt.Printf("Depth: %d\n", *depth)
+	fmt.Printf("Limit: %d\n", *limit)
+	fmt.Printf("Timestamp: %s\n\n", time.Now().UTC().Format(time.RFC3339))
+	fmt.Print(result.String())
+}
+
+func seedBaseline(ctx context.Context, eng *engine.Engine) error {
+	memories := []engine.RememberInput{
+		{Type: "convention", Content: "Use jose for JWT handling across the auth stack", Scope: "project", Project: "bench-project"},
+		{Type: "task", Content: "Run tests with pnpm test --coverage before merge", Scope: "project", Project: "bench-project"},
+		{Type: "bug", Content: "Auth middleware bug: token refresh race can occur without a mutex", Scope: "project", Project: "bench-project"},
+		{Type: "decision", Content: "We chose NATS for event bus reliability and backpressure support", Scope: "project", Project: "bench-project"},
+		{Type: "bug", Content: "Token refresh issue: mutex guards refresh rotation", Scope: "project", Project: "bench-project"},
+		{Type: "spec", Content: "JWT algorithm for compliance is RS256", Scope: "project", Project: "bench-project"},
+		{Type: "bug", Content: "Database query performance bug fixed with DataLoader", Scope: "project", Project: "bench-project"},
+		{Type: "bug", Content: "NATS connection issue solved with keepalive tuning", Scope: "project", Project: "bench-project"},
+		{Type: "spec", Content: "Auth subsystem spec uses jose and RS256 tokens", Scope: "project", Project: "bench-project"},
+		{Type: "task", Content: "Rate limiting task is in progress on public endpoints", Scope: "project", Project: "bench-project"},
+		{Type: "decision", Content: "We chose NATS because it offered simpler ops and better backpressure behavior", Scope: "project", Project: "bench-project"},
+		{Type: "bug", Content: "The token refresh race was caused by missing mutex protection", Scope: "project", Project: "bench-project"},
+		{Type: "decision", Content: "The jose convention was adopted after Edge runtime compatibility issues", Scope: "project", Project: "bench-project"},
+		{Type: "decision", Content: "The last architecture decision was to standardize on NATS", Scope: "project", Project: "bench-project"},
+		{Type: "bug", Content: "Recent bug patterns in auth include refresh token races", Scope: "project", Project: "bench-project"},
+		{Type: "preference", Content: "Testing framework preference is pnpm for JS and TS workspaces", Scope: "project", Project: "bench-project"},
+		{Type: "convention", Content: "Coding conventions: use jose, named exports, and explicit validation", Scope: "project", Project: "bench-project"},
+		{Type: "preference", Content: "TypeScript export style uses named exports only", Scope: "project", Project: "bench-project"},
+		{Type: "task", Content: "Integration tests for auth are required before merge", Scope: "project", Project: "bench-project"},
+		{Type: "spec", Content: "Access token expiry is 15min", Scope: "project", Project: "bench-project"},
+		{Type: "spec", Content: "Refresh token duration is 7d", Scope: "project", Project: "bench-project"},
+		{Type: "file", Content: "Auth middleware file location is auth.ts", Scope: "project", Project: "bench-project"},
+		{Type: "task", Content: "Test coverage command is coverage via pnpm test --coverage", Scope: "project", Project: "bench-project"},
+		{Type: "preference", Content: "Functional programming preference applies in TypeScript modules", Scope: "project", Project: "bench-project"},
+	}
+
+	for _, memory := range memories {
+		if _, err := eng.Remember(ctx, memory); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func must(err error) {
+	if err != nil {
+		panic(err)
+	}
+}
+
+func mustTempDir() string {
+	dir, err := os.MkdirTemp("", "yaad-longmem-core-*")
+	must(err)
+	return dir
+}

benchmark/manifests/README.md

@@ -0,0 +1,9 @@
+# Yaad Benchmark Manifests
+
+This directory is the machine-readable registry for Yaad benchmark suites.
+
+Rules:
+
+- manifests must match the suite ids documented in `../README.md`
+- `published: false` means the suite is official but no committed run is present yet
+- publication directories referenced by manifests must exist

benchmark/manifests/yaad-longmem-core.yaml

@@ -0,0 +1,23 @@
+suite: yaad-longmem-core
+status: shipped
+published: true
+kind: retrieval-quality
+owner: yaad
+source:
+  - yaad/internal/bench/bench.go
+  - yaad/internal/bench/bench_test.go
+runner:
+  command: /bin/zsh -lc 'GOCACHE=$PWD/.gocache go test ./internal/bench -count=1'
+result_format:
+  primary: text_or_markdown_report
+metrics:
+  - r_at_1
+  - r_at_3
+  - r_at_5
+  - r_at_10
+  - mrr
+  - avg_tokens_per_query
+  - duration
+publication_dir: yaad/benchmark/results/yaad-longmem-core
+notes:
+  - This is the current repo-owned retrieval-quality baseline.

benchmark/manifests/yaad-microbench.yaml

@@ -0,0 +1,19 @@
+suite: yaad-microbench
+status: shipped
+published: true
+kind: operational-microbenchmark
+owner: yaad
+source:
+  - yaad/benchmark/benchmark_test.go
+  - yaad/benchmark/compare.md
+runner:
+  command: go test ./benchmark/ -bench=. -benchmem -benchtime=1s
+result_format:
+  primary: text_benchmark_output
+metrics:
+  - latency
+  - allocs_per_op
+  - bytes_per_op
+publication_dir: yaad/benchmark/results/yaad-microbench
+notes:
+  - Use this suite for performance regression baselines and comparison snapshots.

benchmark/results/README.md

@@ -0,0 +1,20 @@
+# Published Yaad Benchmark Runs
+
+This directory is reserved for benchmark runs that are important enough to treat as evidence.
+
+Expected per-run files:
+
+- `report.md`
+- `result.txt` or `result.json`
+- `notes.md`
+
+Only commit runs that are intended to serve as:
+
+- baselines
+- release notes evidence
+- comparison evidence in docs
+
+Current published runs:
+
+- `yaad-longmem-core/2026-06-27/`
+- `yaad-microbench/2026-06-27/`

benchmark/results/yaad-longmem-core/2026-06-27/notes.md

@@ -0,0 +1,11 @@
+# Provenance Notes
+
+- Command:
+  `/bin/zsh -lc 'GOCACHE=$PWD/.gocache go run ./benchmark/cmd/longmemreport --suite default'`
+- Verification:
+  `/bin/zsh -lc 'GOCACHE=$PWD/.gocache go test ./internal/bench -count=1'`
+- Environment:
+  local workspace run on `2026-06-27`
+- Caveats:
+  first-party seeded benchmark harness, not yet LoCoMo/BEAM external dataset ingestion
+  commit SHA was not persisted into the command output in this first baseline

benchmark/results/yaad-longmem-core/2026-06-27/report.md

@@ -0,0 +1,32 @@
+# Yaad LongMem Core Baseline
+
+## Metadata
+
+- Suite: `yaad-longmem-core`
+- Date: `2026-06-27`
+- Model: none
+- Provider: none
+- Commit: current workspace snapshot
+- Command: `/bin/zsh -lc 'GOCACHE=$PWD/.gocache go run ./benchmark/cmd/longmemreport --suite default'`
+
+## Headline Metrics
+
+- R@1: `66.7%`
+- R@3: `88.9%`
+- R@5: `94.4%`
+- R@10: `100.0%`
+- MRR: `0.781`
+- Avg tokens/query: `94`
+- Duration: `15.61675ms`
+
+## Notes
+
+- This is the first committed repo-owned baseline artifact for `yaad-longmem-core`.
+- The run uses the built-in default QA set from `yaad/internal/bench`.
+- The report is generated from a local SQLite-backed seeded memory graph with no external model dependency.
+
+## Comparison Summary
+
+- Previous baseline: none committed
+- Change since baseline: initial published baseline
+- Interpretation: retrieval quality is already strong at broader cutoffs (`R@5`, `R@10`) with room to improve first-rank accuracy.

benchmark/results/yaad-longmem-core/2026-06-27/result.txt

@@ -0,0 +1,13 @@
+Suite: yaad-longmem-core (default)
+Depth: 2
+Limit: 10
+Timestamp: 2026-06-27T03:49:10Z
+
+Benchmark Results (18 questions)
+  R@1:  66.7%
+  R@3:  88.9%
+  R@5:  94.4%
+  R@10: 100.0%
+  MRR:  0.781
+  Avg tokens/query: 94
+  Duration: 15.61675ms

benchmark/results/yaad-longmem-core/README.md

@@ -0,0 +1,13 @@
+# `yaad-longmem-core` Published Runs
+
+Current published runs:
+
+- `2026-06-27/`
+
+Each published run includes:
+
+- `report.md`
+- `result.txt` or `result.json`
+- `notes.md`
+
+Reference manifest: `../../manifests/yaad-longmem-core.yaml`

benchmark/results/yaad-microbench/2026-06-27/notes.md

@@ -0,0 +1,13 @@
+# Provenance Notes
+
+- Command:
+  `/bin/zsh -lc 'GOCACHE=$PWD/.gocache go test ./benchmark -bench=. -benchmem -benchtime=1x'`
+- Environment:
+  `goos=darwin`
+  `goarch=arm64`
+  `cpu=Apple M1`
+- Verification:
+  benchmark command exited successfully with `PASS`
+- Caveats:
+  single-iteration baseline (`-benchtime=1x`) chosen for a fast first committed snapshot
+  output contains temporal tail-marker warnings that should be investigated separately before treating those warnings as acceptable long-term benchmark noise

benchmark/results/yaad-microbench/2026-06-27/report.md

@@ -0,0 +1,32 @@
+# Yaad Microbenchmark Baseline
+
+## Metadata
+
+- Suite: `yaad-microbench`
+- Date: `2026-06-27`
+- Model: none
+- Provider: none
+- Commit: current workspace snapshot
+- Command: `/bin/zsh -lc 'GOCACHE=$PWD/.gocache go test ./benchmark -bench=. -benchmem -benchtime=1x'`
+
+## Headline Metrics
+
+- Remember: `4.41ms/op`, `186496 B/op`, `1838 allocs/op`
+- Recall: `3.74ms/op`, `248232 B/op`, `6639 allocs/op`
+- RecallLargeGraph: `3.28ms/op`, `246336 B/op`, `6617 allocs/op`
+- RecallEmptyQuery: `1.61ms/op`, `17608 B/op`, `483 allocs/op`
+- Context: `1.69ms/op`, `56760 B/op`, `1453 allocs/op`
+- GraphBFS: `2.88ms/op`, `7232 B/op`, `167 allocs/op`
+- HNSWSearch: `584708 ns/op`, `66168 B/op`, `946 allocs/op`
+
+## Notes
+
+- This is the first committed repo-owned baseline artifact for `yaad-microbench`.
+- The command used `-benchtime=1x` to generate a quick, single-iteration baseline suitable for a committed first snapshot.
+- A fuller publication pass may also commit `-benchtime=1s` or longer stabilized runs later.
+
+## Comparison Summary
+
+- Previous baseline: none committed
+- Change since baseline: initial published baseline
+- Interpretation: the current engine is already in the low-single-digit millisecond range for major storage and recall operations on the local benchmark harness.