matrixd: multi-corpus retrieve+merge — SPEC §3.4 component 2 of 5

Lands the matrix indexer's first piece per docs/SPEC.md §3.4:
multi-corpus retrieve+merge with corpus attribution per result.
Future components (relevance filter, downgrade gate, learning-loop
integration) layer on top of this surface.

Architecture:
  - internal/matrix/retrieve.go — Retriever takes (query, corpora,
    k, per_corpus_k), parallel-fans across vectord indexes, merges
    by distance ascending, preserves corpus origin per hit
  - cmd/matrixd — HTTP service on :3217, fronts /v1/matrix/*
  - gateway proxy + [matrixd] config + lakehouse.toml entry
  - Either query_text (matrix calls embedd) or query_vector
    (caller pre-embedded) — vector takes precedence if both set

Error policy: fail-loud on any corpus error. Silent partial returns
would lie about coverage, defeating the matrix's whole purpose.
Bubbles vectord errors as 502 (upstream), validation as 400.

Smoke (scripts/matrix_smoke.sh, 6 assertions PASS first try):
  - /matrix/corpora lists indexes
  - Multi-corpus search returns hits from BOTH corpora
  - Top hit is the globally-closest across all corpora
    (b-near beats a-near at distance 0.05 vs 0.1 — proves merge)
  - Metadata round-trips through the merge
  - Distances ascending in result list
  - Negative paths: empty corpora → 400, missing corpus → 502,
    no query → 400

12-smoke regression sweep all green (D1-D6, G1, G1P, G2,
storaged_cap, pathway, matrix).

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

internal/shared/config.go

@@ -27,6 +27,7 @@ type Config struct {
 	Vectord  VectordConfig `toml:"vectord"`
 	Embedd   EmbeddConfig  `toml:"embedd"`
 	Pathwayd PathwaydConfig `toml:"pathwayd"`
+	Matrixd  MatrixdConfig  `toml:"matrixd"`
 	S3       S3Config      `toml:"s3"`
 	Log      LogConfig     `toml:"log"`
 	Auth     AuthConfig    `toml:"auth"`
@@ -51,9 +52,9 @@ type IngestConfig struct {
 
 // GatewayConfig adds the upstream URLs the reverse proxy fronts.
 // Each route family (/v1/storage, /v1/catalog, /v1/ingest, /v1/sql,
-// /v1/vectors, /v1/embed, /v1/pathway) has its own upstream so we can
-// scale services independently or move them to different boxes without
-// touching gateway code.
+// /v1/vectors, /v1/embed, /v1/pathway, /v1/matrix) has its own
+// upstream so we can scale services independently or move them to
+// different boxes without touching gateway code.
 type GatewayConfig struct {
 	Bind        string `toml:"bind"`
 	StoragedURL string `toml:"storaged_url"`
@@ -63,6 +64,7 @@ type GatewayConfig struct {
 	VectordURL  string `toml:"vectord_url"`
 	EmbeddURL   string `toml:"embedd_url"`
 	PathwaydURL string `toml:"pathwayd_url"`
+	MatrixdURL  string `toml:"matrixd_url"`
 }
 
 // EmbeddConfig drives the embed service. ProviderURL points at the
@@ -96,6 +98,16 @@ type PathwaydConfig struct {
 	PersistPath string `toml:"persist_path"`
 }
 
+// MatrixdConfig drives the matrix-indexer service (cmd/matrixd).
+// Per docs/SPEC.md §3.4: multi-corpus retrieve+merge over vectord
+// with embed-via-embedd for query text. Both upstream URLs are
+// required — matrixd has no in-process fallback.
+type MatrixdConfig struct {
+	Bind       string `toml:"bind"`
+	EmbeddURL  string `toml:"embedd_url"`
+	VectordURL string `toml:"vectord_url"`
+}
+
 // QuerydConfig adds queryd-specific knobs. queryd talks DuckDB
 // directly to MinIO via DuckDB's httpfs extension (so no storaged
 // URL needed), and reads the catalog over HTTP for view registration.
@@ -173,6 +185,7 @@ func DefaultConfig() Config {
 			VectordURL:  "http://127.0.0.1:3215",
 			EmbeddURL:   "http://127.0.0.1:3216",
 			PathwaydURL: "http://127.0.0.1:3217",
+			MatrixdURL:  "http://127.0.0.1:3218",
 		},
 		Storaged: ServiceConfig{Bind: "127.0.0.1:3211"},
 		Catalogd: CatalogConfig{Bind: "127.0.0.1:3212", StoragedURL: "http://127.0.0.1:3211"},
@@ -197,6 +210,11 @@ func DefaultConfig() Config {
 			// PersistPath empty by default = in-memory only. Production
 			// sets to e.g. /var/lib/lakehouse/pathway/state.jsonl.
 		},
+		Matrixd: MatrixdConfig{
+			Bind:       "127.0.0.1:3218",
+			EmbeddURL:  "http://127.0.0.1:3216",
+			VectordURL: "http://127.0.0.1:3215",
+		},
 		Queryd: QuerydConfig{
 			Bind:         "127.0.0.1:3214",
 			CatalogdURL:  "http://127.0.0.1:3212",