G1P: vectord persistence to storaged + scrum (3 fixes incl. 3-way convergent)

Adds optional persistence to vectord (G1's HNSW vector search). Single-
file framed format per index — eliminates the torn-write class that
the 3-way convergent scrum finding identified:

  _vectors/<name>.lhv1  — single binary blob:
      [4 bytes magic "LHV1"]
      [4 bytes envelope_len uint32 BE]
      [envelope bytes — JSON params + metadata + version]
      [graph bytes — raw hnsw.Graph.Export]

Pre-extraction: internal/catalogd/store_client.go → internal/storeclient/
shared package, since both catalogd and vectord need it. Same pattern as
the pre-D5 catalogclient extraction.

Optional via [vectord].storaged_url config (empty = ephemeral mode).
On startup: List + Load each persisted index. After Create / batch Add /
DELETE: Save (or Delete from storaged). Save failures are logged-not-
fatal — in-memory state is the source of truth in flight.

Acceptance smoke G1P 8/8 PASS — kill+restart preserves state, post-
restart search returns dist=0 (graph round-trips exactly), DELETE
removes the file, post-delete restart shows count=0.

All 8 smokes (D1-D6 + G1 + G1P) PASS deterministically. The g1_smoke
gained scripts/g1_smoke.toml that disables persistence so the
in-memory API test stays decoupled from any rehydrate-from-storaged
state contamination.

Cross-lineage scrum on shipped code:
  - Opus 4.7 (opencode):                     1 BLOCK + 5 WARN + 3 INFO
  - Kimi K2-0905 (openrouter):               1 BLOCK + 2 WARN
  - Qwen3-coder (openrouter):                2 BLOCK + 2 WARN + 1 INFO

Fixed (3 — 1 convergent + 2 single-reviewer):
  C1 (Opus + Kimi + Qwen 3-WAY CONVERGENT WARN): Save was non-atomic
    across two PUTs — envelope-succeeds + graph-fails left a half-
    saved index that passed the "both present" List filter and
    silently mismatched metadata against vectors on Load.
    Fix: collapse to single framed file (no torn-write window
    possible).
  O-B1 (Opus BLOCK): isNotFound substring-matched "key not found"
    against the wrapped error message — brittle, any 5xx body
    containing that text would silently misclassify as missing.
    Fix: errors.Is(err, storeclient.ErrKeyNotFound).
  O-I3 (Opus INFO): handleAdd pre-validation only covered id+dim;
    NaN/Inf/zero-norm could still fail mid-batch leaving partial
    commits. Fix: extend pre-validation to call ValidateVector
    (newly exported) per item before any commit.

Dismissed (3 false positives):
  K-B1 + Q-B1 ("safeKey double-escapes %2F segments") — false
    convergent. Wire-protocol escape is decoded by storaged's chi
    router on the way in; on-disk key is the original literal.
    %2F round-trips correctly through PathEscape → URL → chi decode
    → S3 key.
  Q-B2 ("List vulnerable to race conditions") — vectord is single-
    process; no concurrent Save against List in the same vectord.

Deferred (3): rehydrate per-index timeout (G2+ multi-index scale),
saveAfter request ctx (matches G0 timeout deferral), Encode RLock
during slow writer (documented as buffer-only API).

The C1 finding is the strongest signal of the cross-lineage filter:
three independent reviewers all flagged the same torn-write hazard.
Single-file framing eliminates the class — there's now no Persistor
state where envelope and graph can disagree.

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

internal/vectord/index.go

@@ -12,6 +12,7 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
+	"io"
 	"math"
 	"sync"
 
@@ -200,8 +201,15 @@ func (i *Index) resetGraphLocked() {
 	i.g = g
 }
 
+// ValidateVector is the exported form of validateVector — the HTTP
+// handler pre-validates batches before committing, so it needs the
+// same predicate Add uses internally. Per scrum O-I3 (G1P).
+func ValidateVector(vec []float32, distance string) error {
+	return validateVector(vec, distance)
+}
+
 // validateVector rejects vectors that would poison the HNSW
-// graph or produce NaN distances. Per scrum O-W3 (Opus).
+// graph or produce NaN distances. Per scrum O-W3 (Opus, G1).
 func validateVector(vec []float32, distance string) error {
 	var sumSq float64
 	for j, v := range vec {
@@ -259,6 +267,75 @@ func (i *Index) Search(query []float32, k int) ([]Result, error) {
 	return out, nil
 }
 
+// IndexEnvelope is the JSON shape persisted alongside the binary
+// HNSW graph bytes. params + metadata + format version travel
+// together; the graph itself is opaque binary that round-trips
+// through hnsw.Graph.Export / Import.
+type IndexEnvelope struct {
+	Version  int                        `json:"version"`
+	Params   IndexParams                `json:"params"`
+	Metadata map[string]json.RawMessage `json:"metadata"`
+}
+
+// envelopeVersion bumps when the on-disk JSON shape changes
+// incompatibly. Reading a future version returns ErrVersionMismatch
+// rather than producing a half-decoded index.
+const envelopeVersion = 1
+
+// ErrVersionMismatch is returned by DecodeIndex when the envelope
+// claims a version this build doesn't understand.
+var ErrVersionMismatch = errors.New("vectord: unknown envelope version")
+
+// Encode writes the index's JSON envelope (params + metadata) and
+// the binary HNSW graph bytes through two writers. Two-stream
+// shape lets the persistor write each to a distinct storaged key
+// without reframing.
+//
+// envelopeW receives params+metadata as JSON; graphW receives the
+// raw output of hnsw.Graph.Export.
+func (i *Index) Encode(envelopeW, graphW io.Writer) error {
+	i.mu.RLock()
+	defer i.mu.RUnlock()
+
+	env := IndexEnvelope{
+		Version:  envelopeVersion,
+		Params:   i.params,
+		Metadata: i.meta,
+	}
+	if err := json.NewEncoder(envelopeW).Encode(env); err != nil {
+		return fmt.Errorf("encode envelope: %w", err)
+	}
+	if err := i.g.Export(graphW); err != nil {
+		return fmt.Errorf("export graph: %w", err)
+	}
+	return nil
+}
+
+// DecodeIndex reconstructs an Index from a previously-Encoded pair
+// of streams. The returned Index is independent — closing either
+// reader after this call doesn't affect the result.
+func DecodeIndex(envelopeR, graphR io.Reader) (*Index, error) {
+	var env IndexEnvelope
+	if err := json.NewDecoder(envelopeR).Decode(&env); err != nil {
+		return nil, fmt.Errorf("decode envelope: %w", err)
+	}
+	if env.Version != envelopeVersion {
+		return nil, fmt.Errorf("%w: have %d, got %d",
+			ErrVersionMismatch, envelopeVersion, env.Version)
+	}
+	idx, err := NewIndex(env.Params)
+	if err != nil {
+		return nil, err
+	}
+	if err := idx.g.Import(graphR); err != nil {
+		return nil, fmt.Errorf("import graph: %w", err)
+	}
+	if env.Metadata != nil {
+		idx.meta = env.Metadata
+	}
+	return idx, nil
+}
+
 // Lookup returns the stored vector + metadata for an id.
 //
 // Per scrum O-W1 (Opus): the vector is COPIED before return.