BYOK provider embeddings (wave 6 chunk B): kill local transformers

Replace the @huggingface/transformers local embedder (~316MB ONNX cache)
with an EmbeddingPort seam: graph.embeddingModel (nullable "provider:id"
slug) selects an OpenRouter/OpenAI/Gemini adapter, resolved fresh per
call from settings + the auth store so key rotations land immediately.

- src/server/embeddings.ts rewritten: slug grammar, injected-fetch
  adapters (OpenRouter input_type, Gemini taskType batching, OpenAI
  index-ordered rows), honest resolution (null = skip-with-info, set
  model with missing key = honest error), embedNewNodes with model-change
  re-embed wipe + ghost pruning + usage steps, federated catalog
  (OpenRouter /api/v1/embeddings/models — VERIFIED live, the inverse
  path 404s; OpenAI text-embedding- filter; Gemini embedContent filter).
- GET /api/models/embeddings: federated catalog, empty when no keys.
- Extraction tail records stages.embedding usage into the run's money
  channel; EMBEDDING_PRICES overlay in core/prices.ts (outside the
  sync-generated block), callCost falls back to it; cost-summary folds
  the fourth stage; graph-context injection resolves its embedder per
  run, fails honestly when unconfigured, records query tokens.
- Settings: GraphSettings.embeddingModel (null factory), section parser
  validates slug shape (id may contain colons — OpenRouter :free
  suffixes, live catalog fact).
- Removal: @huggingface/transformers uninstalled, PATHS.modelCache and
  onnx tracing entries deleted, @huggingface tracing-excludes guard
  added, stale sharp/libvips comments updated to historical.

Live-verified on port 3004: catalog federates 36 rows (33 OpenRouter +
3 OpenAI), embedNewNodes embedded 10 nodes via the free liquid/lfm-2.5
model (dim 1024, 435 prompt tokens, 1 call, $0), settings PUT rejects
bad slugs with 400.

Gates: typecheck, lint, 895/895 tests, build.

src/agent/subagents/extraction.ts

@@ -505,8 +505,14 @@ export interface RunningExtraction {
 	phase: ExtractionPhase;
 	startedAt: number;
 	/** Live per-stage usage, accumulated as steps bill (the dock's cost /
-	 *  context-window blobs read this through /api/graph/status). */
-	usage: { extractor?: ExtractionStageUsage; auditor?: ExtractionStageUsage };
+	 *  context-window blobs read this through /api/graph/status). Wave 6:
+	 *  the provider-embedding tail became a billable stage — recorded from
+	 *  the embedder's reported usage when present. */
+	usage: {
+		extractor?: ExtractionStageUsage;
+		auditor?: ExtractionStageUsage;
+		embedding?: ExtractionStageUsage;
+	};
 	/** True-cancellation handle (the dock's abort button): one controller per
 	 *  run, shared across phases; abort() cancels the in-flight model call. */
 	controller: AbortController;
@@ -574,9 +580,12 @@ export interface ExtractionModels {
 export interface ExtractionPipelineDeps extends GraphDeps, ExtractionModels {
 	/** The post-merge embedding batch (semantic clusters run on it).
 	 *  INJECTED by the composition root (the agent layer never imports
-	 *  the server layer — architecture law): production passes the real
-	 *  local-model embedder (server/embeddings.ts embedNewNodes), tests
-	 *  fake it. Failure inside it is non-fatal by contract. */
+	 *  the server layer — architecture law): production passes the
+	 *  provider-embedder batch (server/embeddings.ts embedNewNodes — BYOK
+	 *  wave 6; null model = it skips itself with an info log), tests fake
+	 *  it. Failure inside it is non-fatal by contract. When the result
+	 *  carries a `usage` stage (the EmbedBatchResult contract), it is
+	 *  recorded into the run's money-channel capture. */
 	embedder: (graphStore: GraphStore) => Promise<unknown>;
 }
 
@@ -664,6 +673,27 @@ export function createExtractionPipeline(deps: ExtractionPipelineDeps): Extracti
 		run.usage[stage]!.steps.push(usage);
 	}
 
+	/** The embedding tail's failure log (non-fatal by contract). */
+	function recordEmbedFailure(chatId: string): (err: unknown) => undefined {
+		return (err) => {
+			console.error(`[extraction ${chatId}] embedding failed (non-fatal):`, err);
+			return undefined;
+		};
+	}
+
+	/** Wave 6: fold the provider-embedding tail's reported usage into the
+	 *  run's capture — one ExtractionStageUsage per run (the embedder
+	 *  already aggregated its API calls into steps). Absent/skipped/failed
+	 *  embeds contribute nothing (a run that embedded nothing stays
+	 *  two-stage, like the whole local-embedder era). */
+	function captureEmbedUsage(chatId: string, result: unknown): void {
+		const stage = (result as { usage?: ExtractionStageUsage } | undefined)?.usage;
+		if (!stage) return;
+		const run = runningExtractions.get(chatId);
+		if (!run) return;
+		run.usage.embedding = stage;
+	}
+
 
 	async function extract(chatId: string, view: string): Promise<SessionFindings> {
 		const signal = runningExtractions.get(chatId)?.controller.signal;
@@ -739,6 +769,7 @@ export function createExtractionPipeline(deps: ExtractionPipelineDeps): Extracti
 			stages: {
 				extractor: run.usage.extractor ?? { model: "unknown", steps: [] },
 				auditor: run.usage.auditor ?? { model: "unknown", steps: [] },
+				...(run.usage.embedding ? { embedding: run.usage.embedding } : {}),
 			},
 		};
 		if (run.kind === "notes") graphStore.appendSourceUsage(chatId, entry);
@@ -830,9 +861,7 @@ export function createExtractionPipeline(deps: ExtractionPipelineDeps): Extracti
 			// MEANING, so embed the new propositions BEFORE the settle and
 			// the namer look at clusters. Failure is non-fatal — clustering
 			// runs without the new nodes until the next merge retries.
-			await embed(graphStore).catch((err) => {
-				console.error(`[extraction ${chatId}] embedding failed (non-fatal):`, err);
-			});
+			await captureEmbedUsage(chatId, await embed(graphStore).catch(recordEmbedFailure(chatId)));
 			// Option A: the layout ledger evolves with the merge (sync — the
 			// next snapshot fetch must already reflect the new nodes).
 			settleGraphLayout(graphStore);
@@ -963,9 +992,7 @@ export function createExtractionPipeline(deps: ExtractionPipelineDeps): Extracti
 			// (topics from meaning), then the settle, then the namer —
 			// under their own phase, exactly like the chat path.
 			setPhase(id, "embedding", "notes", input.filePath);
-			await embed(graphStore).catch((err) => {
-				console.error(`[extraction ${id}] embedding failed (non-fatal):`, err);
-			});
+			await captureEmbedUsage(id, await embed(graphStore).catch(recordEmbedFailure(id)));
 			// Option A: same post-merge settle as the chat path.
 			settleGraphLayout(graphStore);
 			persistRunUsage(id, Math.round(performance.now() - t0), stats);

src/agent/subagents/graph-context.ts

@@ -12,9 +12,10 @@
  * quiz/ask calls, so delivery lands mid-probing, before plan_init — where
  * prior knowledge matters most.
  *
- * No model call, no usage: the job's only cost is one embedding pass over
- * the warm singleton (tens–~200ms) plus a brute-force cosine scan. It still
- * carries a JobRecord (kind "graph-context") so the dock shows it, and it
+ * No teacher-model call: the job's only model spend is ONE embedding
+ * query (the local embedder was free, provider ones are not — wave 6
+ * records its prompt tokens on the job record). It still carries a
+ * JobRecord (kind "graph-context") so the dock shows it, and it
  * registers its AbortController so the dock's END kills it — but an abort
  * steers NOTHING: nothing was ever promised in the lesson (the injection is
  * server-initiated scaffolding, unlike a teacher-dispatched sub-agent).
@@ -27,6 +28,7 @@
  */
 
 import {
+	accumulateJobUsage,
 	buildGraphContextSteer,
 	steerDelivered,
 	type JobRecord,
@@ -41,20 +43,25 @@ import type { UIMessage } from "ai";
 import { registerJobAbort, unregisterJobAbort } from "./aborts.ts";
 import type { ChatStore, GraphStore, JobStore } from "../../core/ports.ts";
 
-/** The embedder as the runner needs it: the model/dim the ledger must
- *  match (parity: one vector space) + the query seam. Injected so tests
- *  run without the transformer model. */
+/** The embedder as the runner needs it (BYOK wave 6): the model slug the
+ *  ledger must match (parity: one vector space) + the query seam.
+ *  Resolved FRESH per run by the composition root (deps.embedder) so a
+ *  settings PUT or a key save between dispatch and spawn lands; null
+ *  model = no embedding configured — the run skips honestly. The query
+ *  carries its prompt-token count so the job records its spend (the
+ *  local embedder was free; provider ones are not). */
 export interface GraphContextEmbedder {
-	model: string;
-	dim: number;
-	embedQuery: (text: string) => Promise<number[]>;
+	model: string | null;
+	embedQuery: (text: string) => Promise<{ vector: number[]; promptTokens?: number }>;
 }
 
 export interface GraphContextDeps {
 	chatStore: Pick<ChatStore, "getChat">;
 	jobStore: Pick<JobStore, "createJob" | "getJob" | "updateJob" | "findJobByToolCallId">;
 	graphStore: Pick<GraphStore, "readNodes" | "readEvents" | "readEmbeddings">;
-	embedder: GraphContextEmbedder;
+	/** The embedder RESOLVER (wave 6): called once at run start — fresh
+	 *  setting + key reads each run. null = no embedding model configured. */
+	embedder: () => GraphContextEmbedder | null;
 	/** The wake seam — jobs.ts deliverJobResult (resolves on delivery). */
 	deliver: (steer: SteerMessage) => Promise<void>;
 }
@@ -126,7 +133,7 @@ export function startGraphContextInjection(deps: GraphContextDeps, chatId: strin
  *  crash-recovery respawn seam: a job record orphaned "running" by a
  *  process crash re-runs from here (the record is the only input needed). */
 export async function runGraphContextJob(deps: GraphContextDeps, jobId: string): Promise<void> {
-	const { chatStore, jobStore, graphStore, embedder, deliver } = deps;
+	const { chatStore, jobStore, graphStore, deliver } = deps;
 	const job = jobStore.getJob(jobId);
 	if (!job || job.status !== "running") return;
 
@@ -135,6 +142,13 @@ export async function runGraphContextJob(deps: GraphContextDeps, jobId: string):
 	};
 	const chat = chatStore.getChat(job.chatId);
 	if (!chat) return fail(`chat not found: ${job.chatId}`);
+	// BYOK (wave 6): fresh resolution per run; null = honestly off (the
+	// dispatch gate already skips unconfigured sessions — this only fires
+	// on a config change racing a respawn, and the error says exactly why).
+	const embedder = deps.embedder();
+	if (!embedder || embedder.model === null) {
+		return fail("no embedding model configured — injection skipped (graph.embeddingModel is null)");
+	}
 	const topic = topicOf(chat.messages);
 	if (topic === null) return fail("no injectable topic (session past its start)");
 	const budget = effectiveContextBudget(chat.settings);
@@ -146,19 +160,39 @@ export async function runGraphContextJob(deps: GraphContextDeps, jobId: string):
 	try {
 		jobStore.updateJob(jobId, { activity: "embedding topic" });
 		const ledger = graphStore.readEmbeddings();
-		if (ledger.model !== embedder.model || ledger.dim !== embedder.dim) {
-			return fail("embeddings ledger is stale (model/dim mismatch) — injection skipped");
+		// Staleness is the MODEL identity (wave 6): a given model serves one
+		// dim by default, so model parity is space parity; the dim is checked
+		// defensively against the served vector below.
+		if (ledger.model !== embedder.model) {
+			return fail("embeddings ledger is stale (model mismatch) — injection skipped");
 		}
 		if (Object.keys(ledger.vectors).length === 0) {
 			return fail("the knowledge graph has no embeddings yet — nothing to inject");
 		}
 		const query = await embedder.embedQuery(topic);
 		if (controller.signal.aborted) return;
+		// The defensive dim half of the old parity check: a provider-side dim
+		// change (rare) must fail the query, never silently mismatch.
+		if (query.vector.length !== ledger.dim) {
+			return fail(
+				`embedding dim mismatch: query is ${query.vector.length}, ledger holds ${ledger.dim}`,
+			);
+		}
+		// Money channel (wave 6): the one embedding call's prompt tokens fold
+		// into the job record — priced via the EMBEDDING_PRICES overlay.
+		if (query.promptTokens !== undefined) {
+			jobStore.updateJob(jobId, {
+				usage: accumulateJobUsage(job.usage, embedder.model, {
+					inputTokens: query.promptTokens,
+					outputTokens: 0,
+				}),
+			});
+		}
 
 		jobStore.updateJob(jobId, { activity: "selecting propositions" });
 		const data = selectGraphContext({
 			chatId: job.chatId,
-			query,
+			query: query.vector,
 			vectors: ledger.vectors,
 			nodes: graphStore.readNodes(),
 			events: graphStore.readEvents(),

src/agent/subagents/headless.ts

@@ -205,11 +205,13 @@ function svgViewport(svg: string, opts: RenderSvgOptions): { width: number; heig
  *  are an arbitrary SPLIT of one zlib stream, so merging them is the more
  *  standard shape, byte-identical stream, zero re-encoding.
  *
- *  Pure Node on purpose (no sharp): the process already loads transformers'
- *  nested sharp + libvips, and importing the root sharp (Next's optional
- *  dependency) put a SECOND libvips into the process — macOS's ObjC runtime
- *  warns (duplicate GNotificationCenterDelegate, "mysterious crashes").
- *  One native image lib per process; app code carries none. */
+ *  Pure Node on purpose (no sharp): historically the process already carried
+ *  a native image lib via @huggingface/transformers' nested sharp + libvips,
+ *  and importing the root sharp (Next's optional dependency) put a SECOND
+ *  libvips into the process — macOS's ObjC runtime warns (duplicate
+ *  GNotificationCenterDelegate, "mysterious crashes"). The transformers
+ *  embedder died with wave 6 (2026-09-23) but the rule lives on: one native
+ *  image lib per process; app code carries none. */
 export function providerSafePng(png: Buffer): Buffer {
 	const SIG_LEN = 8;
 	if (png.length < SIG_LEN + 12 || png.subarray(0, SIG_LEN).toString("hex") !== "89504e470d0a1a0a") return png;

src/core/contracts/chat.ts

@@ -108,6 +108,10 @@ export interface ExtractionRunUsage {
 	stages: {
 		extractor: ExtractionStageUsage;
 		auditor: ExtractionStageUsage;
+		/** Wave 6 (2026-09-23): the provider-embedding tail — present only
+		 *  when an embedding model is configured and the run embedded
+		 *  (local embeddings were free, so this post-dates them). */
+		embedding?: ExtractionStageUsage;
 	};
 }
 

src/core/cost-summary.ts

@@ -55,10 +55,12 @@ export interface GraphCostSummary {
 	totalDollars: number;
 	/** Runs where EVERY stage was unpriced (totalDollars excludes them). */
 	unpricedRuns: number;
-	/** The three billable pipeline stages (merger/embedder are free). */
+	/** The billable pipeline stages (wave 6: the embedder became one —
+	 *  provider embeddings cost money; merger is the only free stage). */
 	stages: {
 		extraction: StageCost;
 		audit: StageCost;
+		embedding: StageCost;
 		naming: StageCost;
 	};
 	/** Newest first, capped at `recentCap` (default 10). */
@@ -113,6 +115,7 @@ function mergeTokens(into: CallUsage, steps: readonly CallUsage[]): void {
 export function graphCostSummary(input: CostSummaryInput): GraphCostSummary {
 	const extraction = emptyStage();
 	const audit = emptyStage();
+	const embedding = emptyStage();
 	const naming = emptyStage();
 	const runs: RecentRun[] = [];
 
@@ -131,10 +134,25 @@ export function graphCostSummary(input: CostSummaryInput): GraphCostSummary {
 		if (audDollars === null) audit.unpricedRuns++;
 		else audit.dollars += audDollars;
 
-		// Run-level: null only when BOTH stages are unpriced.
-		const priced = extDollars ?? 0;
-		const runDollars = extDollars === null && audDollars === null ? null : priced + (audDollars ?? 0);
-		const allSteps = [...stages.extractor.steps, ...stages.auditor.steps];
+		// Wave 6: the embedding tail — present only when an embedding model
+		// ran (absent stage = the run embedded nothing, never "free").
+		let embDollars: number | null = null;
+		let embSteps: CallUsage[] = [];
+		if (stages.embedding) {
+			embedding.runs++;
+			embSteps = stages.embedding.steps;
+			mergeTokens(embedding.tokens, embSteps);
+			embDollars = stageDollars(stages.embedding.model, embSteps);
+			if (embDollars === null) embedding.unpricedRuns++;
+			else embedding.dollars += embDollars;
+		}
+
+		// Run-level: null only when EVERY stage is unpriced.
+		const allStages: Array<number | null> = [extDollars, audDollars, embDollars];
+		const runDollars = allStages.every((d) => d === null)
+			? null
+			: allStages.reduce<number>((a, d) => a + (d ?? 0), 0);
+		const allSteps = [...stages.extractor.steps, ...stages.auditor.steps, ...embSteps];
 		runs.push({
 			startedAt: run.startedAt,
 			at: run.at,
@@ -177,9 +195,9 @@ export function graphCostSummary(input: CostSummaryInput): GraphCostSummary {
 	// A run is "unpriced" when it billed nothing countable at all.
 	const unpricedRuns = runs.filter((r) => r.dollars === null).length;
 	return {
-		totalDollars: extraction.dollars + audit.dollars + naming.dollars,
+		totalDollars: extraction.dollars + audit.dollars + embedding.dollars + naming.dollars,
 		unpricedRuns,
-		stages: { extraction, audit, naming },
+		stages: { extraction, audit, embedding, naming },
 		runs: capped,
 	};
 }

src/core/ports.ts

@@ -243,3 +243,49 @@ export interface AuthStore {
 	/** Remove one VAR if present (absent = no-op, still a silent success). */
 	deleteAuthVar(name: string): void;
 }
+
+// ─── EmbeddingPort — BYOK provider embeddings (wave 6, 2026-09-23) ───────────
+
+/**
+ * The provider-embedding seam (the local transformers embedder died with
+ * this wave): vectors come from the user's keyed provider — OpenRouter,
+ * OpenAI, or Google — named by graph.embeddingModel ("provider:id", null =
+ * honestly off: embedding/clustering/injection skip with an info log).
+ *
+ * Owner decisions (2026-09-23) baked in:
+ *  - The adapters are resolved FRESH per call from the setting + the auth
+ *    store (key rotations land immediately — the search port's treatment).
+ *  - Vectors are stored as the provider returns them (default dims, no
+ *    truncation, no normalization); the ledger is self-describing on
+ *    model + dim, and any model change voids it (full re-embed).
+ *  - Usage (prompt tokens) flows back to the money channel: adapters
+ *    report it, the caller records it as a CallUsage step.
+ *
+ * Pure types only (browser-safe): the adapters are server-side
+ * (src/server/embeddings.ts) and arrive as injected dependencies.
+ */
+
+/** Which side of retrieval the text is — providers bill identically but
+ *  quality-optimize differently (OpenRouter's input_type, Gemini's
+ *  taskType); every input in one call shares the task. */
+export type EmbeddingTask = "document" | "query";
+
+/** One embedding batch's result: vectors in input order, the model's
+ *  identity + dim (the ledger stamps), and the provider-reported prompt
+ *  token count (undefined = provider didn't report; cost stays honest
+ *  "—" via the existing unpriced path). */
+export interface EmbeddingResult {
+	vectors: number[][];
+	/** The full "provider:id" slug — ledger/cost keys use it verbatim. */
+	model: string;
+	dim: number;
+	promptTokens?: number;
+}
+
+/** A live provider embedding adapter. `embed` throws on failure (adapters
+ *  map HTTP errors to clear Error messages); callers treat failure as
+ *  non-fatal per the extraction contract. */
+export interface EmbeddingPort {
+	model: string;
+	embed(texts: readonly string[], task: EmbeddingTask): Promise<EmbeddingResult>;
+}

src/core/prices.ts

@@ -2752,6 +2752,30 @@ export const CONTEXT_LIMITS: Record<string, number> = {
 
 // ─── Pure helpers (folds + cost inference) ───────────────────────────────────
 
+// ─── Embedding prices (wave 6, 2026-09-23) ─────────────────────────────────
+
+/** Hand-maintained BYOK embedding prices, USD per 1M INPUT tokens — the
+ *  sync script never touches this block (pi-ai's catalogs carry no
+ *  embedding models, so the generated PRICES table has none of these).
+ *  VERIFIED against provider pricing pages 2026-09-23: OpenAI's model
+ *  docs ($0.02 3-small / $0.13 3-large / $0.10 ada-002), Google's pricing
+ *  page ($0.15 gemini-embedding-001 / $0.20 Gemini Embedding 2 text),
+ *  OpenRouter passes provider pricing through. output: 0 — embeddings
+ *  emit no output tokens. Unlisted models stay unpriced ("—", never
+ *  zero); tokens still get captured. */
+export const EMBEDDING_PRICES: Record<string, ModelPrice> = {
+	"openai:text-embedding-3-small": { input: 0.02, output: 0 },
+	"openai:text-embedding-3-large": { input: 0.13, output: 0 },
+	"openai:text-embedding-ada-002": { input: 0.1, output: 0 },
+	"google:gemini-embedding-001": { input: 0.15, output: 0 },
+	"google:gemini-embedding-2": { input: 0.2, output: 0 },
+	"openrouter:openai/text-embedding-3-small": { input: 0.02, output: 0 },
+	"openrouter:openai/text-embedding-3-large": { input: 0.13, output: 0 },
+	"openrouter:openai/text-embedding-ada-002": { input: 0.1, output: 0 },
+	"openrouter:google/gemini-embedding-001": { input: 0.15, output: 0 },
+};
+
+
 /** Sum a list of per-step usages into one CallUsage. A field stays
  *  undefined when EVERY step left it unreported — absent is not zero. */
 export function sumSteps(steps: readonly CallUsage[]): CallUsage {
@@ -2773,7 +2797,8 @@ export function callCost(
 	usage: { inputTokens?: number; outputTokens?: number; cacheReadTokens?: number; cacheWriteTokens?: number },
 	model: string,
 ): number | null {
-	const price = PRICES[model];
+	// Wave 6: the hand-maintained embedding overlay backs the lookup too.
+	const price = PRICES[model] ?? EMBEDDING_PRICES[model];
 	if (!price) return null;
 	if (usage.inputTokens === undefined || usage.outputTokens === undefined) return null;
 	const cacheRead = usage.cacheReadTokens ?? 0;

src/core/settings-resolution.ts

@@ -201,6 +201,9 @@ export function resolveSettings(record: UserSettings | null): EffectiveSettings
 			embedding: graph.embedding ?? FACTORY_SETTINGS.graph.embedding,
 			clustering: graph.clustering ?? FACTORY_SETTINGS.graph.clustering,
 			labeling: graph.labeling ?? FACTORY_SETTINGS.graph.labeling,
+			// BYOK (wave 6): null is the factory floor and a VALID resolved
+			// value — ?? only fills the absent case, null passes through.
+			embeddingModel: graph.embeddingModel ?? FACTORY_SETTINGS.graph.embeddingModel,
 		},
 	};
 }

src/core/settings.ts

@@ -251,6 +251,13 @@ export interface GraphSettings {
 	clustering?: boolean;
 	/** The LLM cluster-namer (needs clustering). */
 	labeling?: boolean;
+	/** BYOK embeddings (wave 6, 2026-09-23): the provider embedding model
+	 *  as a "provider:id" slug (openrouter:…, openai:…, google:…). null =
+	 *  no model — embedding/clustering/injection skip honestly (info log,
+	 *  graph stays textual); no factory floor exists. Keys live in the auth
+	 *  store, resolved fresh per call. A model CHANGE re-embeds everything
+	 *  (the ledger's staleness semantics). */
+	embeddingModel?: string | null;
 }
 
 /** THE record. Every section optional (delta); unknown top-level keys are
@@ -303,7 +310,7 @@ export const FACTORY_SETTINGS: FactorySettings = {
 		sessionNameSerif: true,
 		mdRendering: { headingWeight: 900, boldColor: null, italicColor: null },
 	},
-	graph: { enabled: true, embedding: true, clustering: true, labeling: true },
+	graph: { enabled: true, embedding: true, clustering: true, labeling: true, embeddingModel: null },
 };
 
 // ─── Sanitizer ─────────────────────────────────────────────────────────────
@@ -453,6 +460,14 @@ function sanitizeGraph(raw: Record<string, unknown>): GraphSettings {
 	if (clustering !== undefined) out.clustering = clustering;
 	const labeling = boolOrDrop(raw.labeling);
 	if (labeling !== undefined) out.labeling = labeling;
+	// BYOK embeddings (wave 6): null or a provider-qualified slug; anything
+	// else (bad type, bad shape) DROPS to absent — an invalid write never
+	// becomes a live model (the PUT parser 400s it first; this is the
+	// read-side belt-and-suspenders for hand-edited files).
+	if (raw.embeddingModel === null) out.embeddingModel = null;
+	else if (typeof raw.embeddingModel === "string" && /^\S+:\S+$/.test(raw.embeddingModel)) {
+		out.embeddingModel = raw.embeddingModel;
+	}
 	return out;
 }
 

src/server/chat-handler.ts

@@ -5,7 +5,7 @@ import { piEngineForSpec, type PiEngine } from "../agent/models.ts";
 import { createJobRunner } from "../agent/subagents/runner.ts";
 import { createExtractionPipeline } from "../agent/subagents/extraction.ts";
 import { runGraphContextJob, type GraphContextDeps } from "../agent/subagents/graph-context.ts";
-import { EMBEDDING_DIM, EMBEDDING_MODEL, embedNewNodes, embedQuery } from "./embeddings.ts";
+import { embedNewNodes, embeddingPort } from "./embeddings.ts";
 import type { ModelRole } from "../../config.ts";
 import { claimSteers, deliverJobResult, setContextRespawn, setJobRespawn, setTurnRunner } from "./jobs.ts";
 import { recordToPiMessages } from "./pi/record-adapter.ts";
@@ -63,8 +63,8 @@ const jobRunner = createJobRunner({
  *  (/api/graph/import) hit the same single-flight registry. */
 export const extraction = createExtractionPipeline({
 	...stores,
-	// The REAL embedder (local transformer model): post-merge embedding
-	// batch — semantic clusters are computed and persisted here.
+	// The provider-embedder batch (BYOK wave 6): post-merge embedding —
+	// resolves the model fresh per call; null model = info-skip inside.
 	embedder: embedNewNodes,
 	// BYOK (owner, 2026-09-22): the extraction stages resolve the chain —
 	// role override → slot → NOTHING — read FRESH per stage call; an empty
@@ -75,14 +75,27 @@ export const extraction = createExtractionPipeline({
 });
 
 /** Graph context injection (vision-context-injection.md): the runner's
- *  deps — same storage ports, the REAL embedder as the query seam (same
- *  warm singleton as extraction, so vector-space parity holds by
- *  construction), and the wake pipeline as the delivery seam. */
+ *  deps — same storage ports, the provider-embedder RESOLVER as the query
+ *  seam (BYOK wave 6: fresh setting + key reads per run, so vector-space
+ *  parity with the ledger is checked against the CURRENT model; a key or
+ *  settings PUT between dispatch and spawn lands), and the wake pipeline
+ *  as the delivery seam. */
 export const graphContext: GraphContextDeps = {
 	chatStore: stores.chatStore,
 	jobStore: stores.jobStore,
 	graphStore: stores.graphStore,
-	embedder: { model: EMBEDDING_MODEL, dim: EMBEDDING_DIM, embedQuery },
+	embedder: () => {
+		const resolved = embeddingPort();
+		if (!resolved.ok) return null;
+		const port = resolved.port;
+		return {
+			model: port.model,
+			embedQuery: async (text: string) => {
+				const result = await port.embed([text], "query");
+				return { vector: result.vectors[0]!, promptTokens: result.promptTokens };
+			},
+		};
+	},
 	deliver: deliverJobResult,
 };
 
@@ -221,7 +234,10 @@ export async function handleChatRequest(
 	// GRAPH GATES (settings-storage wave, 2026-09-19): the read channel
 	// needs BOTH the master switch and the embedding rung (injection is a
 	// vector query); with graph off there is no context job at all.
-	if (graphContextEnabled(effective.graph)) {
+	// BYOK (wave 6): an unconfigured embedding model means no vectors to
+	// query — the dispatch skips honestly (the runner's own resolution is
+	// the belt-and-suspenders for respawn races).
+	if (graphContextEnabled(effective.graph) && effective.graph.embeddingModel !== null) {
 		triggerGraphContext(graphContext, chatId);
 	}
 

src/server/embeddings.ts

@@ -1,94 +1,293 @@
 /**
- * THE EMBEDDER (DECIDED 2026-09-13): semantic topic clustering needs
- * vectors, and vectors need a model running ON the user's machine — no
- * external services, no API bills, no network dependency for re-embedding.
+ * BYOK PROVIDER EMBEDDINGS (wave 6, 2026-09-23): the local transformers
+ * embedder is dead — vectors now come from the user's keyed provider
+ * (OpenRouter / OpenAI / Google), named by graph.embeddingModel
+ * ("provider:id", null = honestly off; skip with an info log, the graph
+ * stays textual — owner ruling 2026-09-23).
  *
- * Runtime: in-process transformers.js (@huggingface/transformers v4 over
- * onnxruntime-node — native Apple Silicon acceleration). The model
- * weights download ONCE to the local HF cache on first run (~300MB).
+ * Owner decisions baked in:
+ *  - NO factory model (BYOK, like the model slots): null is the floor.
+ *  - Adapters resolve FRESH per call from the setting + the auth store
+ *    (the search port's treatment — key rotations land immediately); a
+ *    key missing for a SET model is an honest error, never a fallback.
+ *  - Vectors stored as the provider returns them (default dims, no
+ *    truncation, no normalization). The ledger is self-describing on
+ *    model + dim; a model change voids it (full re-embed, minutes at
+ *    current scale — the local embedder's same staleness rule).
+ *  - Usage (prompt tokens) flows to the money channel: every API call
+ *    reports one CallUsage step (outputTokens: 0 — embeddings emit no
+ *    output; priced via the hand-maintained EMBEDDING_PRICES overlay).
  *
- * Model: EmbeddingGemma-300M (q8) — best quality-per-megabyte small
- * embedding model as of late 2025 (MTEB-en 68.36), built for on-device
- * use, with MRL truncation so we store 512 of its 768 dims. Every input
- * uses the model card's document format ("title: none | text: …"),
- * consistently — mixing prefixed and unprefixed inputs degrades quality.
- *
- * Model swaps re-embed EVERYTHING: vectors from different models live in
- * incompatible spaces. The ledger records model + dim; a mismatch marks
- * the whole ledger stale and this module re-embeds from scratch (minutes
- * at current scale).
+ * The adapters are injected-fetch dependencies so tests never touch the
+ * network; wire protocols VERIFIED against provider docs 2026-09-23:
+ *  - OpenRouter: POST /api/v1/embeddings (Bearer), input_type
+ *    search_document|search_query; catalog GET /api/v1/embeddings/models
+ *    (VERIFIED live 2026-09-23 — the inverse path /api/v1/models/
+ *    embeddings 404s).
+ *  - OpenAI: POST /v1/embeddings (Bearer); catalog GET /v1/models.
+ *  - Google: POST /v1beta/models/{m}:batchEmbedContents (x-goog-api-key),
+ *    taskType RETRIEVAL_DOCUMENT|RETRIEVAL_QUERY; catalog GET /v1beta/models
+ *    filtered on supportedGenerationMethods ∋ embedContent.
  */
-import * as fs from "node:fs";
-import { env, pipeline, type FeatureExtractionPipeline } from "@huggingface/transformers";
-import { PATHS } from "../../config.ts";
-import type { EmbeddingsLedger, GraphNode } from "../core/contracts.ts";
+
+import type { CallUsage, EmbeddingsLedger, GraphNode } from "../core/contracts.ts";
+import type { ExtractionStageUsage } from "../core/contracts/chat.ts";
+import type { EmbeddingPort, EmbeddingResult, EmbeddingTask } from "../core/ports.ts";
 import { semanticClusters, SEMANTIC_SIM_THRESHOLD } from "../core/semantic-clusters.ts";
+import { keyValue } from "./keys.ts";
+import { effectiveSettings } from "./stores.ts";
 
-export const EMBEDDING_MODEL = "onnx-community/embeddinggemma-300m-ONNX";
-/** MRL truncation of the native 768 — negligible quality loss, half the
- *  ledger size (2026-09-13 researcher sweep). */
-export const EMBEDDING_DIM = 512;
-/** Batch size bounds peak memory; propositions are tiny so 32 per call
- *  keeps the pipeline warm without thrashing. */
+/** The wire-callable shape the adapters close over (tests inject a stub). */
+type FetchLike = (input: string, init: RequestInit) => Promise<Response>;
+
+/** One provider embedding API call — kept small enough to never trip
+ * per-request input limits (propositions are tiny; 32 was the local
+ * embedder's batch and it stays). */
 const EMBED_BATCH = 32;
+/** Per-request timeout: a hung provider call must not hang an extraction
+ * run (the wave-1 hung-job lesson). */
+const REQUEST_TIMEOUT_MS = 60_000;
 
-// Model cache routing (Electron seam, 2026-09-17): the default cacheDir
-// lives inside node_modules — read-only inside a packaged .app bundle.
-// When LH_DATA_DIR is set the cache follows the data seam (userData);
-// in dev it stays at the package default (the model is already there).
-if (PATHS.modelCache) {
-	fs.mkdirSync(PATHS.modelCache, { recursive: true });
-	env.cacheDir = PATHS.modelCache;
+/** The providers this wave ships + their auth vars (the curated key
+ * catalog, same ids the auth store and /api/keys use). */
+const PROVIDER_KEYS = {
+	openrouter: "OPENROUTER_API_KEY",
+	openai: "OPENAI_API_KEY",
+	google: "GEMINI_API_KEY",
+} as const;
+export type EmbeddingProviderId = keyof typeof PROVIDER_KEYS;
+
+/** "provider:id" → {provider, id}; null when malformed (no guessing). */
+export function parseEmbeddingModelSlug(slug: string): { provider: EmbeddingProviderId; id: string } | null {
+	const colon = slug.indexOf(":");
+	if (colon <= 0 || colon === slug.length - 1) return null;
+	const provider = slug.slice(0, colon) as EmbeddingProviderId;
+	if (!(provider in PROVIDER_KEYS)) return null;
+	return { provider, id: slug.slice(colon + 1) };
 }
 
-let pipelinePromise: Promise<FeatureExtractionPipeline> | null = null;
+// ─── Adapters (one per provider; pure injected-fetch factories) ──────────────
 
-function getPipeline(): Promise<FeatureExtractionPipeline> {
-	pipelinePromise ??= pipeline("feature-extraction", EMBEDDING_MODEL, { dtype: "q8" });
-	return pipelinePromise;
+/** Shared: HTTP-error → clear Error (the search adapters' mapping). */
+async function demandOk(resp: Response, label: string): Promise<void> {
+	if (resp.ok) return;
+	const body = await resp.text();
+	throw new Error(`${label} API ${resp.status}: ${body.slice(0, 200)}`);
 }
 
-/** EmbeddingGemma's required document format (model card). */
-function embedInput(statement: string): string {
-	return `title: none | text: ${statement}`;
+/** Shared: normalize a provider's {embedding, index} rows to input order. */
+function rowsInOrder(
+	data: Array<{ embedding?: unknown; index?: unknown }>,
+	count: number,
+	label: string,
+): number[][] {
+	const byIndex = new Map<number, number[]>();
+	for (const row of data) {
+		if (
+			Array.isArray(row.embedding) &&
+			row.embedding.every((x) => typeof x === "number") &&
+			typeof row.index === "number"
+		) {
+			byIndex.set(row.index, row.embedding as number[]);
+		}
+	}
+	const out: number[][] = [];
+	for (let i = 0; i < count; i++) {
+		const vec = byIndex.get(i);
+		if (!vec) throw new Error(`${label} API returned ${byIndex.size}/${count} vectors`);
+		out.push(vec);
+	}
+	return out;
 }
 
-/** EmbeddingGemma's retrieval-QUERY format (model card) — the topic side of
- *  graph context injection (vision-context-injection.md). Role-asymmetric
- *  BY DESIGN: queries and documents use different trained templates; the
- *  requirement is same model + same truncation (one vector space), each
- *  side in the format the model was trained for. */
-function queryInput(text: string): string {
-	return `task: search result | query: ${text}`;
+/** One API call's money-channel step: embeddings emit no output, cache
+ *  nothing, reason never — the fields exist (CallUsage requires them) as
+ *  absent-is-not-zero undefineds. */
+function embeddingStep(promptTokens: number): CallUsage {
+	return {
+		inputTokens: promptTokens,
+		outputTokens: 0,
+		cacheReadTokens: undefined,
+		cacheWriteTokens: undefined,
+		reasoningTokens: undefined,
+	};
 }
 
-/** Embed one retrieval query (the session's topic) — same warm singleton,
- *  same 512-dim MRL truncation as the ledger. The one embedding call the
- *  injection job makes; tens–~200ms warm. */
-export async function embedQuery(text: string): Promise<number[]> {
-	const extractor = await getPipeline();
-	const output = await extractor([queryInput(text)], { pooling: "mean", normalize: true });
-	return truncateNormalize((output.tolist() as number[][])[0]!);
+/** OpenRouter: POST https://openrouter.ai/api/v1/embeddings — Bearer auth,
+ * input_type hints the retrieval side (verified against the docs 2026-09-23). */
+export function openrouterEmbeddingProvider(model: string, apiKey: string, fetchFn: FetchLike = fetch): EmbeddingPort {
+	const parsed = parseEmbeddingModelSlug(model);
+	if (!parsed) throw new Error(`invalid embedding model slug: ${model}`);
+	return {
+		model,
+		async embed(texts: readonly string[], task: EmbeddingTask): Promise<EmbeddingResult> {
+			const resp = await fetchFn("https://openrouter.ai/api/v1/embeddings", {
+				method: "POST",
+				headers: { "content-type": "application/json", authorization: `Bearer ${apiKey}` },
+				body: JSON.stringify({
+					model: parsed.id,
+					input: texts,
+					input_type: task === "query" ? "search_query" : "search_document",
+				}),
+				signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+			});
+			await demandOk(resp, "OpenRouter embeddings");
+			const data = (await resp.json()) as {
+				data?: Array<{ embedding?: unknown; index?: unknown }>;
+				usage?: { prompt_tokens?: number };
+			};
+			return {
+				vectors: rowsInOrder(data.data ?? [], texts.length, "OpenRouter embeddings"),
+				model,
+				dim: 0, // filled by the caller from the first vector (below)
+				promptTokens: data.usage?.prompt_tokens,
+			};
+		},
+	};
 }
 
-/** Truncate an L2-normalized vector to EMBEDDING_DIM (MRL: leading dims
- *  carry most of the signal) and re-normalize so cosine = dot product. */
-function truncateNormalize(vec: readonly number[]): number[] {
-	const out = vec.slice(0, EMBEDDING_DIM);
-	let mag = 0;
-	for (const x of out) mag += x * x;
-	mag = Math.sqrt(mag);
-	return mag > 0 ? out.map((x) => x / mag) : out;
+/** OpenAI: POST https://api.openai.com/v1/embeddings — Bearer auth; the
+ * response's usage carries prompt_tokens (verified 2026-09-23). */
+export function openaiEmbeddingProvider(model: string, apiKey: string, fetchFn: FetchLike = fetch): EmbeddingPort {
+	const parsed = parseEmbeddingModelSlug(model);
+	if (!parsed) throw new Error(`invalid embedding model slug: ${model}`);
+	return {
+		model,
+		async embed(texts: readonly string[], task: EmbeddingTask): Promise<EmbeddingResult> {
+			// OpenAI's embeddings API takes no task hint (one format per
+			// model); the argument exists for seam parity and is unused here.
+			void task;
+			const resp = await fetchFn("https://api.openai.com/v1/embeddings", {
+				method: "POST",
+				headers: { "content-type": "application/json", authorization: `Bearer ${apiKey}` },
+				body: JSON.stringify({ model: parsed.id, input: texts }),
+				signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+			});
+			await demandOk(resp, "OpenAI embeddings");
+			const data = (await resp.json()) as {
+				data?: Array<{ embedding?: unknown; index?: unknown }>;
+				usage?: { prompt_tokens?: number };
+			};
+			return {
+				vectors: rowsInOrder(data.data ?? [], texts.length, "OpenAI embeddings"),
+				model,
+				dim: 0,
+				promptTokens: data.usage?.prompt_tokens,
+			};
+		},
+	};
+}
+
+/** Google: POST …/models/{m}:batchEmbedContents — x-goog-api-key, one
+ * request per text with taskType RETRIEVAL_QUERY|RETRIEVAL_DOCUMENT
+ * (verified against the Gemini API docs 2026-09-23). */
+export function googleEmbeddingProvider(model: string, apiKey: string, fetchFn: FetchLike = fetch): EmbeddingPort {
+	const parsed = parseEmbeddingModelSlug(model);
+	if (!parsed) throw new Error(`invalid embedding model slug: ${model}`);
+	return {
+		model,
+		async embed(texts: readonly string[], task: EmbeddingTask): Promise<EmbeddingResult> {
+			const resp = await fetchFn(
+				`https://generativelanguage.googleapis.com/v1beta/models/${encodeURIComponent(parsed.id)}:batchEmbedContents`,
+				{
+					method: "POST",
+					headers: { "content-type": "application/json", "x-goog-api-key": apiKey },
+					body: JSON.stringify({
+						requests: texts.map((text) => ({
+							model: `models/${parsed.id}`,
+							content: { parts: [{ text }] },
+							taskType: task === "query" ? "RETRIEVAL_QUERY" : "RETRIEVAL_DOCUMENT",
+						})),
+					}),
+					signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+				},
+			);
+			await demandOk(resp, "Google embeddings");
+			const data = (await resp.json()) as {
+				embeddings?: Array<{ values?: unknown }>;
+				/** embedContent responses carry usageMetadata; the batch
+				 * shape may too — parsed opportunistically, never guessed. */
+				usageMetadata?: { promptTokenCount?: number };
+			};
+			const vectors = (data.embeddings ?? []).map((row, i) => {
+				if (!Array.isArray(row.values) || !row.values.every((x) => typeof x === "number")) {
+					throw new Error(`Google embeddings API returned a bad vector at index ${i}`);
+				}
+				return row.values as number[];
+			});
+			if (vectors.length !== texts.length) {
+				throw new Error(`Google embeddings API returned ${vectors.length}/${texts.length} vectors`);
+			}
+			return { vectors, model, dim: 0, promptTokens: data.usageMetadata?.promptTokenCount };
+		},
+	};
+}
+
+// ─── Resolution (fresh per call — the search port's treatment) ───────────────
+
+/** The resolved state: a live port, or the honest reason it isn't. */
+export type EmbeddingResolution =
+	| { ok: true; port: EmbeddingPort }
+	| { ok: false; reason: string };
+
+/** Pure resolution from a setting slug + a key lookup (testable): null
+ *  slug = off; a set slug with no key = honest unavailability. */
+export function resolveEmbeddingPortFor(
+	slug: string | null | undefined,
+	keyOf: (envVar: string) => string | undefined,
+	fetchFn?: FetchLike,
+): EmbeddingResolution {
+	if (slug === null || slug === undefined || slug === "") {
+		return { ok: false, reason: "no embedding model configured (graph.embeddingModel is null)" };
+	}
+	const parsed = parseEmbeddingModelSlug(slug);
+	if (!parsed) {
+		return { ok: false, reason: `invalid embedding model slug: ${slug}` };
+	}
+	const apiKey = keyOf(PROVIDER_KEYS[parsed.provider]);
+	if (!apiKey) {
+		return {
+			ok: false,
+			reason: `embedding model is set to "${slug}" but its ${PROVIDER_KEYS[parsed.provider]} key is missing`,
+		};
+	}
+	const factory =
+		parsed.provider === "openrouter"
+			? openrouterEmbeddingProvider
+			: parsed.provider === "openai"
+				? openaiEmbeddingProvider
+				: googleEmbeddingProvider;
+	return { ok: true, port: factory(slug, apiKey, fetchFn) };
+}
+
+/** The LIVE resolution — reads the settings record + auth store fresh on
+ *  every call, so a settings PUT or a key save lands on the next call. */
+export function embeddingPort(): EmbeddingResolution {
+	return resolveEmbeddingPortFor(effectiveSettings().graph.embeddingModel, keyValue);
+}
+
+// ─── The post-merge batch (the extraction pipeline's embedding tail) ────────
+
+/** What the embedding tail reports back: counts for logs, the skip reason
+ *  when nothing ran (owner ruling: null model = info skip, not error), and
+ *  the money-channel stage when it billed (one CallUsage step per API call,
+ *  outputTokens: 0 — priced via EMBEDDING_PRICES). */
+export interface EmbedBatchResult {
+	embedded: number;
+	total: number;
+	skipped?: string;
+	usage?: ExtractionStageUsage;
 }
 
 /**
  * Embed every node the ledger is missing — the post-merge hook (new
  * propositions only, typically a handful) AND the cold-start backfill
- * (empty ledger = every node) in one function. Model/dim mismatch voids
- * the ledger first (full re-embed). Also prunes vectors for nodes that
- * no longer exist. Writes the whole ledger and returns counts for logs.
- * Non-fatal by contract: the caller treats failure as "clustering runs
- * without the new nodes until the next merge retries".
+ * (empty ledger = every node) in one function. A model change voids the
+ * ledger first (full re-embed — vectors from different models live in
+ * incompatible spaces). Also prunes vectors for nodes that no longer
+ * exist, then re-clusters ONCE per batch (consumers read the persisted
+ * partition). Non-fatal by contract: the caller treats failure as
+ * "clustering runs without the new nodes until the next merge retries".
  */
 export async function embedNewNodes(
 	graphStore: {
@@ -96,10 +295,21 @@ export async function embedNewNodes(
 		readEmbeddings(): EmbeddingsLedger;
 		writeEmbeddings(ledger: EmbeddingsLedger): void;
 	},
-): Promise<{ embedded: number; total: number }> {
+	/** Test seam: the live resolution by default; tests inject a scripted
+	 *  port (they never read the machine's settings/auth files). */
+	resolvePort: () => EmbeddingResolution = embeddingPort,
+): Promise<EmbedBatchResult> {
+	const resolved = resolvePort();
 	const ledger = graphStore.readEmbeddings();
-	const stale = ledger.model !== EMBEDDING_MODEL || ledger.dim !== EMBEDDING_DIM;
+	if (!resolved.ok) {
+		console.info(`[embeddings] skipped — ${resolved.reason}`);
+		return { embedded: 0, total: Object.keys(ledger.vectors).length, skipped: resolved.reason };
+	}
+	const port = resolved.port;
+	const stale = ledger.model !== port.model;
 	const vectors: Record<string, number[]> = stale ? {} : { ...ledger.vectors };
+	const steps: NonNullable<EmbedBatchResult["usage"]>["steps"] = [];
+	let dim = ledger.dim;
 
 	// Node LINES may repeat an id — dedupe, first defines (getGraph rule).
 	const seen = new Set<string>();
@@ -110,18 +320,20 @@ export async function embedNewNodes(
 		if (!vectors[node.id]) todo.push(node);
 	}
 
-	if (todo.length > 0) {
-		const extractor = await getPipeline();
-		for (let i = 0; i < todo.length; i += EMBED_BATCH) {
-			const batch = todo.slice(i, i + EMBED_BATCH);
-			const output = await extractor(batch.map((n) => embedInput(n.statement)), {
-				pooling: "mean",
-				normalize: true,
-			});
-			const rows = output.tolist() as number[][];
-			for (let j = 0; j < batch.length; j++) {
-				vectors[batch[j]!.id] = truncateNormalize(rows[j]!);
-			}
+	for (let i = 0; i < todo.length; i += EMBED_BATCH) {
+		const batch = todo.slice(i, i + EMBED_BATCH);
+		const result = await port.embed(
+			batch.map((n) => n.statement),
+			"document",
+		);
+		for (let j = 0; j < batch.length; j++) {
+			vectors[batch[j]!.id] = result.vectors[j]!;
+		}
+		if (result.vectors[0]) dim = result.vectors[0].length;
+		if (result.promptTokens !== undefined) {
+			// outputTokens: 0 — embeddings emit no output; callCost needs it
+			// defined to price the input at all.
+			steps.push(embeddingStep(result.promptTokens));
 		}
 	}
 
@@ -135,20 +347,112 @@ export async function embedNewNodes(
 	}
 
 	// RECLUSTER AT THE END OF THE BATCH (user-decided 2026-09-13): the
-	// agglomerative pass is ~1.5s at current scale, so it runs HERE —
-	// once per embedding batch — and consumers (snapshot, settle, namer)
-	// read the persisted partition instead of recomputing per read.
+	// agglomerative pass runs HERE — once per embedding batch — and
+	// consumers (snapshot, settle, namer) read the persisted partition.
 	const clusters = semanticClusters(vectors, { similarityThreshold: SEMANTIC_SIM_THRESHOLD });
 
 	const wrote = todo.length > 0 || pruned > 0 || stale || ledger.clusters.length !== clusters.length;
 	if (wrote) {
 		graphStore.writeEmbeddings({
-			model: EMBEDDING_MODEL,
-			dim: EMBEDDING_DIM,
+			model: port.model,
+			dim,
 			vectors,
 			clusters,
 			updatedAt: new Date().toISOString(),
 		});
 	}
-	return { embedded: todo.length, total: Object.keys(vectors).length };
+	return {
+		embedded: todo.length,
+		total: Object.keys(vectors).length,
+		usage: steps.length > 0 ? { model: port.model, steps } : undefined,
+	};
+}
+// ─── The federated embedding catalog (wave 6, owner ruling 2026-09-23) ──────
+
+/** One catalog row: provider-qualified id (the setting's exact slug
+ *  format) + display name. */
+export interface EmbeddingCatalogModel {
+	/** The full "provider:id" slug — what graph.embeddingModel stores. */
+	id: string;
+	/** Human label for the picker (the provider's name, when given). */
+	name: string;
+}
+
+/** The embedding models of every KEYED provider, fetched live (the
+ *  chat-models picker is a static pi-ai catalog, but pi-ai carries no
+ *  embedding models — so this endpoint federates the providers' own
+ *  lists). A provider without a key contributes nothing; a provider whose
+ *  catalog call fails is skipped with an error log (never poisons the
+ *  rest, never fails the endpoint). Empty array = nothing keyed. */
+export async function embeddingModelCatalog(
+	fetchFn: FetchLike = fetch,
+	/** Test seam: the live key lookup by default; tests inject scripted
+	 *  keys (they never read the machine's auth file). */
+	keyOf: (id: string) => string | undefined = keyValue,
+): Promise<EmbeddingCatalogModel[]> {
+	const out: EmbeddingCatalogModel[] = [];
+	const fetchJson = async (url: string, headers: Record<string, string>): Promise<unknown> => {
+		const resp = await fetchFn(url, { headers, signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS) });
+		await demandOk(resp, "Embeddings catalog");
+		return resp.json();
+	};
+
+	// OpenRouter: GET /api/v1/embeddings/models — the dedicated embedding
+	// list (VERIFIED live 2026-09-23: the inverse path /api/v1/models/
+	// embeddings 404s; this one returns {data: [{id, name, …}]}). Paginated
+	// — limit=500 covers the whole list at current size (33).
+	if (keyOf(PROVIDER_KEYS.openrouter)) {
+		try {
+			const data = (await fetchJson("https://openrouter.ai/api/v1/embeddings/models?limit=500", {
+				authorization: `Bearer ${keyOf(PROVIDER_KEYS.openrouter)}`,
+			})) as { data?: Array<{ id?: unknown; name?: unknown }> };
+			for (const m of data.data ?? []) {
+				if (typeof m.id !== "string" || !m.id) continue;
+				out.push({ id: `openrouter:${m.id}`, name: typeof m.name === "string" && m.name ? m.name : m.id });
+			}
+		} catch (err) {
+			console.error("[embeddings] OpenRouter catalog fetch failed:", err);
+		}
+	}
+
+	// OpenAI: GET /v1/models — no embedding-only list, so filter the
+	// generic one on the embedding naming convention.
+	if (keyOf(PROVIDER_KEYS.openai)) {
+		try {
+			const data = (await fetchJson("https://api.openai.com/v1/models", {
+				authorization: `Bearer ${keyOf(PROVIDER_KEYS.openai)}`,
+			})) as { data?: Array<{ id?: unknown }> };
+			for (const m of data.data ?? []) {
+				if (typeof m.id !== "string" || !/^text-embedding-/.test(m.id)) continue;
+				out.push({ id: `openai:${m.id}`, name: m.id });
+			}
+		} catch (err) {
+			console.error("[embeddings] OpenAI catalog fetch failed:", err);
+		}
+	}
+
+	// Google: GET /v1beta/models — filter on the methods the model
+	// actually serves (embedContent present).
+	if (keyOf(PROVIDER_KEYS.google)) {
+		try {
+			const data = (await fetchJson("https://generativelanguage.googleapis.com/v1beta/models?pageSize=1000", {
+				"x-goog-api-key": keyOf(PROVIDER_KEYS.google)!,
+			})) as {
+				models?: Array<{ name?: unknown; displayName?: unknown; supportedGenerationMethods?: unknown }>;
+			};
+			for (const m of data.models ?? []) {
+				if (typeof m.name !== "string" || !m.name.startsWith("models/")) continue;
+				if (!Array.isArray(m.supportedGenerationMethods) || !m.supportedGenerationMethods.includes("embedContent")) continue;
+				const id = m.name.slice("models/".length);
+				out.push({
+					id: `google:${id}`,
+					name: typeof m.displayName === "string" && m.displayName ? m.displayName : id,
+				});
+			}
+		} catch (err) {
+			console.error("[embeddings] Google catalog fetch failed:", err);
+		}
+	}
+
+	return out;
 }

src/server/index.ts

@@ -6,6 +6,7 @@
 
 export * from "./chat-handler.ts";
 export * from "./chats.ts";
+export * from "./embeddings.ts";
 export * from "./graph.ts";
 export * from "./commit-positions.ts";
 export * from "./jobs.ts";

src/server/settings-body.ts

@@ -277,7 +277,11 @@ export function parseAppearanceSettingsBody(body: unknown): SettingsBodyResult<A
 	return { ok: true, settings };
 }
 
-/** graph: the four-rung ladder { enabled?, embedding?, clustering?, labeling? }. */
+/** graph: the four-rung ladder { enabled?, embedding?, clustering?, labeling? }
+ *  + embeddingModel? — the BYOK provider embedding model (wave 6,
+ *  2026-09-23): null or a "provider:id" slug of a shipped provider.
+ *  Catalog validity is network-dependent — the parser checks SHAPE only
+ *  (the federated /api/models/embeddings gives the picker real options). */
 export function parseGraphSettingsBody(body: unknown): SettingsBodyResult<GraphSettings> {
 	const raw = asRecord(body);
 	if (!raw) return { ok: false, error: "Invalid JSON body" };
@@ -290,6 +294,25 @@ export function parseGraphSettingsBody(body: unknown): SettingsBodyResult<GraphS
 			settings[key] = raw[key];
 		}
 	}
+	if (raw.embeddingModel !== undefined) {
+		if (raw.embeddingModel !== null) {
+			// NOTE: the id may itself contain colons (OpenRouter suffixes like
+			// "liquid/lfm-2.5-embedding-350m:free") — the provider is the part
+			// before the FIRST colon, so the id half just forbids whitespace.
+			if (
+				typeof raw.embeddingModel !== "string" ||
+				!/^(openrouter|openai|google):\S+$/.test(raw.embeddingModel)
+			) {
+				return {
+					ok: false,
+					error: 'embeddingModel must be null or a "openrouter|openai|google:model-id" slug',
+				};
+			}
+			settings.embeddingModel = raw.embeddingModel;
+		} else {
+			settings.embeddingModel = null;
+		}
+	}
 	return { ok: true, settings };
 }