matrix: playbook memory + boost — SPEC §3.4 component 5 of 5 (LEARNING LOOP)

Closes SPEC §3.4. The matrix indexer is now a learning meta-index per
feedback_meta_index_vision.md — every successful (query → answer)
pair recorded via /matrix/playbooks/record boosts that answer for
future similar queries.

This is the architectural piece that lifts vectord from "static
hybrid search" to the meta-index J originally framed in Phase 19 of
the Rust system.

What's new:
  - internal/matrix/playbook.go — PlaybookEntry, PlaybookHit,
    ApplyPlaybookBoost. Pure-function boost math:
      distance' = distance * (1 - 0.5 * score)
    Score 0 = no boost (factor 1.0); score 1 = halve distance
    (factor 0.5). Capped at 0.5 deliberately so a single high-
    confidence playbook can't dominate the base ranking forever
    (runaway-feedback-loop guard).
  - Retriever.Record(entry, corpus) — embeds query_text, ensures
    playbook corpus exists (idempotent), upserts via deterministic
    sha256-derived ID (last score wins on re-record of same triple).
  - Retriever.Search extended with UsePlaybook + PlaybookCorpus +
    PlaybookTopK + PlaybookMaxDistance. Reuses the query vector —
    no extra embed call. Missing-corpus 404 = no-op (cold-start
    state before any Record call), not an error.
  - POST /v1/matrix/playbooks/record (matrixd) — caller submits
    {query_text, answer_id, answer_corpus, score, tags?}; gets
    {playbook_id} back.

Storage: a vectord index named "playbook_memory" (configurable per
request) with embed(query_text) as the vector and the
PlaybookEntry JSON as metadata. Just another corpus — observable
from /vectors/index, persistable through G1P, etc.

Match key for boost: (AnswerID, AnswerCorpus). Cross-corpus ID
collisions don't false-match — verified by
TestApplyPlaybookBoost_CorpusAttributionRespected.

End-to-end smoke (scripts/playbook_smoke.sh, all assertions PASS):
  - Baseline search: widget-c at distance 0.6566 (rank 3)
  - Record playbook: query → widget-c, score=1.0
  - Re-search with use_playbook=true:
      widget-c distance: 0.3283 (rank 2)
      ratio: 0.5 EXACTLY (matches boost math precisely)
      playbook_boosted: 1
  - widget-c jumped from #3 to #2 — learning loop visible

Tests:
  - 8 unit tests in internal/matrix/playbook_test.go covering
    Validate, BoostFactor (5 cases), the no-boost identity, the
    boost-moves-result-up scenario, highest-score wins on duplicate
    matches, cross-corpus attribution, JSON round-trip, and
    rejection of empty metadata
  - scripts/playbook_smoke.sh integration test (3 assertions PASS)

15-smoke regression sweep all green (D1-D6, G1, G1P, G2,
storaged_cap, pathway, matrix, relevance, downgrade, playbook).

SPEC §3.4 NOW COMPLETE: 5 of 5 components shipped. The matrix
indexer's port is done as a substrate; remaining work is operational
(rating signal sources, telemetry, eventual structured filtering for
staffing data — none in §3.4).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

cmd/matrixd/main.go

@@ -2,12 +2,13 @@
 // Retriever with HTTP routes per docs/SPEC.md §3.4.
 //
 // Routes:
-//   POST /matrix/search     — multi-corpus retrieve+merge
-//   GET  /matrix/corpora    — list known vectord indexes (proxy)
-//   POST /matrix/relevance  — adjacency-pollution filter (CODE-aware;
-//                              port of mcp-server/relevance.ts)
-//   POST /matrix/downgrade  — strong-model auto-downgrade decision
-//                              (port of mode.rs::execute pass5 gate)
+//   POST /matrix/search             — multi-corpus retrieve+merge,
+//                                      with optional playbook boost
+//   GET  /matrix/corpora            — list known vectord indexes
+//   POST /matrix/relevance          — adjacency-pollution filter
+//   POST /matrix/downgrade          — strong-model downgrade gate
+//   POST /matrix/playbooks/record   — record a (query → answer)
+//                                      success for the learning loop
 //
 // matrixd talks to embedd (for query-text embedding) and vectord
 // (for per-corpus search) via HTTP. Both URLs come from
@@ -64,6 +65,7 @@ func (h *handlers) register(r chi.Router) {
 	r.Get("/matrix/corpora", h.handleCorpora)
 	r.Post("/matrix/relevance", h.handleRelevance)
 	r.Post("/matrix/downgrade", h.handleDowngrade)
+	r.Post("/matrix/playbooks/record", h.handlePlaybookRecord)
 }
 
 func (h *handlers) handleSearch(w http.ResponseWriter, r *http.Request) {
@@ -104,6 +106,42 @@ func (h *handlers) handleRelevance(w http.ResponseWriter, r *http.Request) {
 	writeJSON(w, http.StatusOK, res)
 }
 
+// playbookRecordRequest is the POST /matrix/playbooks/record body.
+// Corpus is optional; defaults to matrix.DefaultPlaybookCorpus.
+type playbookRecordRequest struct {
+	QueryText    string   `json:"query_text"`
+	AnswerID     string   `json:"answer_id"`
+	AnswerCorpus string   `json:"answer_corpus"`
+	Score        float64  `json:"score"`
+	Tags         []string `json:"tags,omitempty"`
+	Corpus       string   `json:"corpus,omitempty"`
+}
+
+func (h *handlers) handlePlaybookRecord(w http.ResponseWriter, r *http.Request) {
+	var req playbookRecordRequest
+	if !decodeJSON(w, r, &req) {
+		return
+	}
+	entry := matrix.NewPlaybookEntry(req.QueryText, req.AnswerID, req.AnswerCorpus, req.Score, req.Tags)
+	if err := entry.Validate(); err != nil {
+		http.Error(w, err.Error(), http.StatusBadRequest)
+		return
+	}
+	pbID, err := h.r.Record(r.Context(), entry, req.Corpus)
+	if err != nil {
+		slog.Warn("playbook record", "err", err)
+		http.Error(w, err.Error(), http.StatusBadGateway)
+		return
+	}
+	writeJSON(w, http.StatusOK, map[string]any{
+		"playbook_id":   pbID,
+		"query_text":    entry.QueryText,
+		"answer_id":     entry.AnswerID,
+		"answer_corpus": entry.AnswerCorpus,
+		"score":         entry.Score,
+	})
+}
+
 // downgradeRequest is the POST /matrix/downgrade body. Mirrors
 // matrix.DowngradeInput; ForceFullOverride is read from the
 // LH_FORCE_FULL_ENRICHMENT env var when omitted from the body.