@maxgfr/codeindex 2.10.0 → 2.11.1

package/src/embed/encode.ts

@@ -87,14 +87,36 @@ export function roundHalfToEven(x: number): number {
   return f % 2 === 0 ? f : f + 1; // exactly .5 → nearest even
 }
 
+// L2-normalize a float vector and quantize it to int8 at the fixed 1/127 scale
+// (round-half-to-even, clamp to [-127,127]) — the SHARED tail of both tiers. The
+// static encoder feeds its mean-pooled vector here; the endpoint tier feeds each
+// float embedding it receives. Because the quantization is byte-identical, a
+// given float vector maps to the same int8 bytes and the integer-dot ranking is
+// consistent across tiers. A zero-norm input yields an all-zero vector (never
+// NaN — it simply ranks last).
+export function quantize(vec: ArrayLike<number>): Int8Array {
+  const dim = vec.length;
+  const out = new Int8Array(dim);
+  let sumsq = 0;
+  for (let d = 0; d < dim; d++) sumsq += vec[d]! * vec[d]!;
+  const norm = Math.sqrt(sumsq);
+  if (norm === 0) return out; // zero vector — nothing to rank on
+  for (let d = 0; d < dim; d++) {
+    let q = roundHalfToEven((vec[d]! / norm) * QUANT);
+    if (q > QUANT) q = QUANT;
+    else if (q < -QUANT) q = -QUANT;
+    out[d] = q;
+  }
+  return out;
+}
+
 // Encode a text to an int8 unit-ish vector. Empty / all-OOV / zero-norm inputs
 // yield an all-zero vector (dot-products against it are 0 — it simply ranks
 // last), never NaN. Pure and deterministic: same model + text → same bytes.
 export function encode(model: StaticEmbedModel, text: string): Int8Array {
   const { dim, weights } = model;
-  const out = new Int8Array(dim);
   const ids = tokenize(text, model);
-  if (ids.length === 0) return out;
+  if (ids.length === 0) return new Int8Array(dim);
 
   // mean-pool in double precision, fixed order.
   const pooled = new Float64Array(dim);
@@ -105,20 +127,8 @@ export function encode(model: StaticEmbedModel, text: string): Int8Array {
   const inv = 1 / ids.length;
   for (let d = 0; d < dim; d++) pooled[d]! *= inv;
 
-  // L2-normalize.
-  let sumsq = 0;
-  for (let d = 0; d < dim; d++) sumsq += pooled[d]! * pooled[d]!;
-  const norm = Math.sqrt(sumsq);
-  if (norm === 0) return out; // zero vector — nothing to rank on
-
-  // quantize to int8 at the fixed 1/127 scale, round-half-to-even, clamp.
-  for (let d = 0; d < dim; d++) {
-    let q = roundHalfToEven((pooled[d]! / norm) * QUANT);
-    if (q > QUANT) q = QUANT;
-    else if (q < -QUANT) q = -QUANT;
-    out[d] = q;
-  }
-  return out;
+  // L2-normalize + int8-quantize (the shared tail, identical to the endpoint tier).
+  return quantize(pooled);
 }
 
 // Integer dot product of two int8 vectors (the ranking primitive). Widened to a

package/src/embed/endpoint.ts

@@ -1,40 +1,77 @@
-// HTTP embedding endpoint client — the "rich" tier SKELETON for v2.11.0. It is
-// intentionally NOT wired into the CLI or MCP in v2.10.0: the deterministic
-// static tier is the default, and an endpoint's vectors are float and provider-
-// dependent (NOT byte-deterministic), so this stays an explicit, opt-in escape
-// hatch a future release finalizes. Shipped now only so the module surface is
-// stable and the contract is documented.
+// HTTP embedding endpoint client — the "rich" tier (v2.11.0). The engine becomes
+// a CONSUMER of a local containerized embedding server (e.g.
+// ghcr.io/maxgfr/codeindex-embed): it POSTs corpus/query texts, receives float
+// vectors, and runs them through the EXACT SAME L2-normalize + int8-quantize
+// pipeline as the static tier (encode.ts `quantize`), so ranking stays a pure
+// integer dot product. Node >=18 has global fetch, so this stays zero-dependency.
 //
-// The contract (v2.11): POST { texts: string[] } → { vectors: number[][] } to
-// CODEINDEX_EMBED_ENDPOINT (or opts.url). Node >=18 has global fetch, so this
-// stays zero-dependency. The library never orchestrates docker; running such a
-// server (e.g. ghcr.io/maxgfr/codeindex-embed) is a user/CI concern.
+// The contract: POST { texts: string[] } → { vectors: number[][] } to
+// `${base}/embed`, plus GET `${base}/healthz`. `base` is CODEINDEX_EMBED_ENDPOINT
+// (or opts.url). The library NEVER orchestrates docker; running the server is a
+// user/CI concern (`codeindex embed serve` only prints/runs the docker command).
+//
+// DETERMINISM: this tier is deterministic PER IMAGE DIGEST (the model is baked
+// into a pinned image), NOT byte-golden — endpoint float vectors are provider-
+// dependent. That is why endpoint indexes are built at search time and never
+// serialized to embeddings.bin (which carries a determinism guarantee).
+
+import type { RepoScan } from "../scan.js";
+import { quantize } from "./encode.js";
+import { EMBED_VERSION } from "./model.js";
+import { embeddingUnits, type EmbeddingIndex, type EmbeddingRecord } from "./index.js";
 
 export interface EmbedEndpointOptions {
-  // Endpoint URL. Falls back to CODEINDEX_EMBED_ENDPOINT when omitted.
+  // Endpoint BASE url (e.g. http://localhost:8756). Falls back to
+  // CODEINDEX_EMBED_ENDPOINT when omitted.
   url?: string;
-  // Abort the request after this many ms (default 30_000).
+  // Abort a request after this many ms (default from CODEINDEX_EMBED_TIMEOUT_MS,
+  // else 30_000).
   timeoutMs?: number;
   // Extra request headers (e.g. an auth token for a private endpoint).
   headers?: Record<string, string>;
+  // Max texts per POST /embed request when embedding a corpus (default 64).
+  batchSize?: number;
 }
 
-// Resolve the configured endpoint URL, or undefined when neither opts.url nor
-// CODEINDEX_EMBED_ENDPOINT is set — the silent "endpoint tier unavailable" signal.
+// Resolve the configured endpoint BASE url, or undefined when neither opts.url
+// nor CODEINDEX_EMBED_ENDPOINT is set — the "endpoint tier not requested" signal.
 export function resolveEmbedEndpoint(opts: EmbedEndpointOptions = {}): string | undefined {
   const url = opts.url ?? process.env.CODEINDEX_EMBED_ENDPOINT;
   return url && url.trim() ? url.trim() : undefined;
 }
 
-// Request float embeddings for a batch of texts from the endpoint. Throws a
-// clear error when no endpoint is configured or the response is malformed; the
-// caller decides whether to degrade. NOTE: endpoint vectors are float and are
-// NOT part of any determinism guarantee — this path is for the rich tier only.
+function stripTrailingSlash(url: string): string {
+  return url.replace(/\/+$/, "");
+}
+
+// The POST /embed URL for a base. Idempotent when the base already ends in
+// /embed (so pointing the env straight at the embed route also works).
+export function embedEndpointUrl(base: string): string {
+  const b = stripTrailingSlash(base);
+  return b.endsWith("/embed") ? b : b + "/embed";
+}
+
+// The GET /healthz URL for a base (tolerates a base that already ends in /embed).
+export function healthzUrl(base: string): string {
+  return stripTrailingSlash(base).replace(/\/embed$/, "") + "/healthz";
+}
+
+function resolveTimeout(opts: EmbedEndpointOptions): number {
+  if (typeof opts.timeoutMs === "number") return opts.timeoutMs;
+  const env = Number(process.env.CODEINDEX_EMBED_TIMEOUT_MS);
+  return Number.isFinite(env) && env > 0 ? env : 30_000;
+}
+
+// Request float embeddings for a batch of texts from the endpoint's /embed
+// route. Throws a clear error when no endpoint is configured, the request times
+// out / fails, or the response is malformed; the caller decides whether to
+// degrade. NOTE: endpoint vectors are float and are NOT byte-deterministic.
 export async function embedViaEndpoint(texts: string[], opts: EmbedEndpointOptions = {}): Promise<number[][]> {
-  const url = resolveEmbedEndpoint(opts);
-  if (!url) throw new Error("no embedding endpoint configured (set CODEINDEX_EMBED_ENDPOINT or pass opts.url)");
+  const base = resolveEmbedEndpoint(opts);
+  if (!base) throw new Error("no embedding endpoint configured (set CODEINDEX_EMBED_ENDPOINT or pass opts.url)");
+  const url = embedEndpointUrl(base);
   const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), opts.timeoutMs ?? 30_000);
+  const timer = setTimeout(() => controller.abort(), resolveTimeout(opts));
   try {
     const res = await fetch(url, {
       method: "POST",
@@ -53,3 +90,55 @@ export async function embedViaEndpoint(texts: string[], opts: EmbedEndpointOptio
     clearTimeout(timer);
   }
 }
+
+// Is the endpoint reachable? GETs /healthz and returns true only on a 2xx. Never
+// throws — a down/timed-out endpoint returns false (used by `embed status`).
+export async function probeEndpoint(base: string, opts: EmbedEndpointOptions = {}): Promise<boolean> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), resolveTimeout(opts));
+  try {
+    const res = await fetch(healthzUrl(base), { signal: controller.signal, headers: opts.headers });
+    return res.ok;
+  } catch {
+    return false;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// Encode ONE query string via the endpoint → int8 vector, run through the shared
+// quantize pipeline (so it lives in the same int8 space as an endpoint-built
+// corpus). Throws on an unreachable/malformed endpoint — the caller degrades.
+export async function encodeQueryViaEndpoint(query: string, opts: EmbedEndpointOptions = {}): Promise<Int8Array> {
+  const [vec] = await embedViaEndpoint([query], opts);
+  if (!vec) throw new Error("embedding endpoint returned no vector for the query");
+  return quantize(vec);
+}
+
+// Build the int8 corpus index by embedding every corpus unit (the SAME units the
+// static tier uses) via the endpoint, batched, then quantizing each float vector
+// through the shared L2+int8 pipeline. The result plugs straight into
+// searchSemantic's integer-dot ranking. Built at search time (never serialized).
+export async function buildEndpointIndex(scan: RepoScan, opts: EmbedEndpointOptions = {}): Promise<EmbeddingIndex> {
+  const units = embeddingUnits(scan);
+  const batchSize = opts.batchSize && opts.batchSize > 0 ? opts.batchSize : 64;
+  const records: EmbeddingRecord[] = [];
+  let dim = 0;
+  for (let i = 0; i < units.length; i += batchSize) {
+    const batch = units.slice(i, i + batchSize);
+    const vectors = await embedViaEndpoint(batch.map((u) => u.text), opts);
+    if (vectors.length !== batch.length) {
+      throw new Error(`embedding endpoint returned ${vectors.length} vectors for ${batch.length} texts`);
+    }
+    for (let j = 0; j < batch.length; j++) {
+      const u = batch[j]!;
+      const vec = quantize(vectors[j]!);
+      if (vec.length > dim) dim = vec.length;
+      const rec: EmbeddingRecord = { file: u.file, vec };
+      if (u.symbol !== undefined) rec.symbol = u.symbol;
+      if (u.line !== undefined) rec.line = u.line;
+      records.push(rec);
+    }
+  }
+  return { embedVersion: EMBED_VERSION, modelId: "endpoint", dim, records };
+}

package/src/embed/index.ts

@@ -34,11 +34,21 @@ function fileText(rel: string, title: string | undefined, summary: string | unde
   return [title ?? "", summary ?? "", ...headings, rel.replace(/\//g, " ")].join("\n");
 }
 
-// Build the corpus embedding index from a scan + a loaded model. Pure and
-// deterministic (encode is byte-stable, scan order is fixed) → two builds of an
-// unchanged repo produce byte-identical serialized bytes.
-export function buildEmbeddingIndex(scan: RepoScan, model: StaticEmbedModel): EmbeddingIndex {
-  const records: EmbeddingRecord[] = [];
+// One corpus item to embed: its target (file, optional symbol/line) plus the
+// exact text to encode. This is the SINGLE definition of "what the corpus is",
+// shared by the static tier (buildEmbeddingIndex) and the endpoint tier
+// (buildEndpointIndex) so both embed byte-identical texts in the same order and
+// differ ONLY in the encoder. Deterministic: scan order (files by rel) then
+// declaration order within a file, deduped by symbol name (bm25 parity).
+export interface EmbeddingUnit {
+  file: string;
+  symbol?: string;
+  line?: number;
+  text: string;
+}
+
+export function embeddingUnits(scan: RepoScan): EmbeddingUnit[] {
+  const units: EmbeddingUnit[] = [];
   for (const f of scan.files) {
     const seen = new Set<string>();
     let hadSymbol = false;
@@ -46,20 +56,26 @@ export function buildEmbeddingIndex(scan: RepoScan, model: StaticEmbedModel): Em
       if (seen.has(s.name)) continue; // dedupe by name within a file (bm25 parity)
       seen.add(s.name);
       hadSymbol = true;
-      records.push({
-        file: f.rel,
-        symbol: s.name,
-        line: s.line,
-        vec: encode(model, symbolText(f.rel, s.name, s.signature, f.summary)),
-      });
+      units.push({ file: f.rel, symbol: s.name, line: s.line, text: symbolText(f.rel, s.name, s.signature, f.summary) });
     }
     if (!hadSymbol) {
       const text = fileText(f.rel, f.title, f.summary, f.headings);
-      if (text.replace(/\s+/g, "")) {
-        records.push({ file: f.rel, vec: encode(model, text) });
-      }
+      if (text.replace(/\s+/g, "")) units.push({ file: f.rel, text });
     }
   }
+  return units;
+}
+
+// Build the corpus embedding index from a scan + a loaded model. Pure and
+// deterministic (encode is byte-stable, scan order is fixed) → two builds of an
+// unchanged repo produce byte-identical serialized bytes.
+export function buildEmbeddingIndex(scan: RepoScan, model: StaticEmbedModel): EmbeddingIndex {
+  const records: EmbeddingRecord[] = embeddingUnits(scan).map((u) => {
+    const rec: EmbeddingRecord = { file: u.file, vec: encode(model, u.text) };
+    if (u.symbol !== undefined) rec.symbol = u.symbol;
+    if (u.line !== undefined) rec.line = u.line;
+    return rec;
+  });
   return { embedVersion: EMBED_VERSION, modelId: model.modelId, dim: model.dim, records };
 }
 

package/src/embed/search.ts

@@ -13,6 +13,10 @@ export interface SemanticSearchOptions extends SearchOptions {
   // The loaded static model, needed to encode the QUERY into the same int8 space
   // as the corpus. Absent → the search degrades to pure lexical (no throw).
   model?: StaticEmbedModel;
+  // A pre-encoded int8 query vector — the endpoint tier's escape hatch: it has
+  // no local model but has already quantized the endpoint's float query vector
+  // through the SAME pipeline as the corpus. Wins over `model` when both are set.
+  queryVec?: Int8Array;
   // RRF damping (default 60), exposed for parity with the shared rrf helper.
   rrfK?: number;
 }
@@ -45,11 +49,13 @@ export function searchSemantic(
   // fuse meaningfully, then trim after fusion.
   const lexical = searchIndex(scan, query, { limit: Math.max(limit, 50), fuzzy: opts.fuzzy });
 
-  if (!opts.model || !index || index.records.length === 0) {
+  // Resolve the query vector: an already-encoded one (endpoint tier) wins;
+  // otherwise encode via the local model. No vector, no index, or an empty index
+  // → pure-lexical degradation.
+  const q = opts.queryVec ?? (opts.model ? encode(opts.model, query) : undefined);
+  if (!q || !index || index.records.length === 0) {
     return lexical.slice(0, limit); // pure-lexical degradation
   }
-
-  const q = encode(opts.model, query);
   // Best (highest integer dot) record per file, remembering its symbol.
   const bestByFile = new Map<string, { score: number; symbol?: string }>();
   for (const r of index.records) {

package/src/engine-cli.ts

@@ -22,6 +22,13 @@ import { checkRules, parseRules } from "./rules.js";
 import { EMBED_VERSION, resolveEmbedModelDir, loadEmbedModel, resolveEmbedPullUrl } from "./embed/model.js";
 import { buildEmbeddingIndex, serializeEmbeddings } from "./embed/index.js";
 import { searchSemantic } from "./embed/search.js";
+import {
+  resolveEmbedEndpoint,
+  buildEndpointIndex,
+  encodeQueryViaEndpoint,
+  probeEndpoint,
+} from "./embed/endpoint.js";
+import { have, sh } from "./util.js";
 
 const HELP = `codeindex engine v${ENGINE_VERSION} — deterministic repo indexing
 
@@ -41,13 +48,17 @@ Commands:
   grep        Search: cli.mjs grep <pattern> --repo <dir> (JSON hits)
   search      Keyless BM25 lexical search over symbol names, path segments,
               markdown headings and summaries: cli.mjs search "<query>" --repo <dir>.
-              --semantic fuses in the deterministic static-embedding tier (RRF)
-              when a model is present; degrades to lexical (exit 0) when absent
-  embed       Deterministic static-embedding tier (opt-in by model asset):
-                embed status   Report the resolved model + EMBED_VERSION (JSON)
-                embed build    Write embeddings.bin into --out <dir> from the repo
+              --semantic fuses in an embedding tier (RRF) — the HTTP endpoint
+              (CODEINDEX_EMBED_ENDPOINT) if set, else a local static model;
+              degrades to lexical (exit 0) when neither is available/reachable
+  embed       Embedding tiers (opt-in). Precedence: endpoint > static model:
+                embed status   Effective mode (none/static/endpoint), model +
+                               EMBED_VERSION, and endpoint reachability (JSON)
+                embed build    Write embeddings.bin into --out <dir> (static tier)
                 embed pull     Fetch the model asset into CODEINDEX_EMBED_DIR (or
                                <repo>/.codeindex/models/) — needs CODEINDEX_EMBED_URL
+                embed serve    Print (or --run) the docker command that starts the
+                               containerized embedding server (rich tier)
   rules       Architecture rules (forbidden edges, cycles, orphans) validated
               against the link-graph: --config <codeindex.rules.json>; exits 1
               on any error-severity violation (a CI gate)
@@ -75,8 +86,10 @@ Flags:
   --limit <n>         Max results for \`search\` (default 20)
   --no-fuzzy          \`search\`: disable trigram fuzzy fallback for query terms
                       with zero document frequency (default: enabled)
-  --semantic          \`search\`: RRF-fuse the deterministic static-embedding tier
-                      with lexical (needs a model asset; lexical-only otherwise)
+  --semantic          \`search\`: RRF-fuse an embedding tier with lexical — the
+                      HTTP endpoint if CODEINDEX_EMBED_ENDPOINT is set, else a
+                      local static model (lexical-only when neither is available)
+  --run               \`embed serve\`: run the docker command instead of printing it
   --recall            \`callers\`: recall-oriented binding (issue #7) — relaxes
                       the JS/TS import gate to unique repo-wide names and labels
                       each site corroborated|unique-name
@@ -101,6 +114,7 @@ interface CliFlags {
   fuzzy: boolean; // search: trigram fuzzy fallback for df==0 terms (default true)
   semantic: boolean; // search: RRF-fuse the static-embedding tier (default false)
   recall?: boolean; // callers: recall-oriented binding
+  run?: boolean; // `embed serve`: actually run the docker command (default: print)
   projectRoot?: string; // scip: override Metadata.project_root
   positional?: string; // e.g. the grep pattern or search query
 }
@@ -141,6 +155,7 @@ function parseFlags(args: string[]): CliFlags {
     else if (a === "--no-fuzzy") flags.fuzzy = false;
     else if (a === "--semantic") flags.semantic = true;
     else if (a === "--recall") flags.recall = true;
+    else if (a === "--run") flags.run = true;
     else if (!a.startsWith("--") && flags.positional === undefined) flags.positional = a;
     else throw new Error(`unknown flag: ${a}`);
   }
@@ -264,20 +279,42 @@ export async function runCli(argv: string[]): Promise<void> {
     if (!flags.positional) throw new Error('search needs a query: cli.mjs search "<query>" --repo <dir>');
     const scan = scanRepo(flags.repo, scanOptions(flags));
     if (flags.semantic) {
-      const modelDir = resolveEmbedModelDir(flags.repo);
-      const model = modelDir ? loadEmbedModel(modelDir) : undefined;
-      if (!model) {
-        // Degradation: --semantic without a model → lexical results + a stderr
-        // note, exit 0. The results shape is a superset of the lexical one.
-        process.stderr.write(
-          "codeindex: semantic search unavailable (no embedding model present) — returning lexical results; run `codeindex embed pull` to enable it\n",
-        );
-        const results = searchIndex(scan, flags.positional, { limit: flags.limit, fuzzy: flags.fuzzy });
+      const endpoint = resolveEmbedEndpoint();
+      const lexical = (): void => {
+        const results = searchIndex(scan, flags.positional!, { limit: flags.limit, fuzzy: flags.fuzzy });
         emit(JSON.stringify(results, null, 2) + "\n", flags.out);
+      };
+      if (endpoint) {
+        // Rich tier. The endpoint takes PRECEDENCE over a local static model:
+        // configuring CODEINDEX_EMBED_ENDPOINT is an explicit user intent. An
+        // unreachable/timed-out/malformed endpoint degrades straight to lexical
+        // (a stderr note, exit 0) — NOT to the static model.
+        try {
+          const index = await buildEndpointIndex(scan);
+          const queryVec = await encodeQueryViaEndpoint(flags.positional);
+          const results = searchSemantic(scan, flags.positional, index, { queryVec, limit: flags.limit, fuzzy: flags.fuzzy });
+          emit(JSON.stringify(results, null, 2) + "\n", flags.out);
+        } catch (e) {
+          process.stderr.write(
+            `codeindex: embedding endpoint ${endpoint} unavailable (${e instanceof Error ? e.message : e}) — returning lexical results\n`,
+          );
+          lexical();
+        }
       } else {
-        const index = buildEmbeddingIndex(scan, model);
-        const results = searchSemantic(scan, flags.positional, index, { model, limit: flags.limit, fuzzy: flags.fuzzy });
-        emit(JSON.stringify(results, null, 2) + "\n", flags.out);
+        const modelDir = resolveEmbedModelDir(flags.repo);
+        const model = modelDir ? loadEmbedModel(modelDir) : undefined;
+        if (!model) {
+          // Degradation: --semantic without a model or endpoint → lexical results
+          // + a stderr note, exit 0. The results shape is a superset of lexical.
+          process.stderr.write(
+            "codeindex: semantic search unavailable (no embedding model or endpoint) — returning lexical results; run `codeindex embed pull` or set CODEINDEX_EMBED_ENDPOINT to enable it\n",
+          );
+          lexical();
+        } else {
+          const index = buildEmbeddingIndex(scan, model);
+          const results = searchSemantic(scan, flags.positional, index, { model, limit: flags.limit, fuzzy: flags.fuzzy });
+          emit(JSON.stringify(results, null, 2) + "\n", flags.out);
+        }
       }
     } else {
       const results = searchIndex(scan, flags.positional, { limit: flags.limit, fuzzy: flags.fuzzy });
@@ -288,14 +325,54 @@ export async function runCli(argv: string[]): Promise<void> {
     const modelDir = resolveEmbedModelDir(flags.repo);
     if (sub === "status") {
       const model = modelDir ? loadEmbedModel(modelDir) : undefined;
-      const status = {
+      const endpoint = resolveEmbedEndpoint();
+      // Effective mode with precedence: endpoint > static model > none.
+      const mode: "none" | "static" | "endpoint" = endpoint ? "endpoint" : model ? "static" : "none";
+      const status: Record<string, unknown> = {
         embedVersion: EMBED_VERSION,
+        mode,
         model: model
           ? { present: true, dir: modelDir, modelId: model.modelId, dim: model.dim, vocabSize: model.vocabSize }
           : { present: false },
-        endpoint: process.env.CODEINDEX_EMBED_ENDPOINT ?? null,
+        endpoint: endpoint ?? null,
       };
+      // When an endpoint is configured, actually probe its reachability.
+      if (endpoint) status.endpointReachable = await probeEndpoint(endpoint);
       emit(JSON.stringify(status, null, 2) + "\n", flags.out);
+    } else if (sub === "serve") {
+      // Convenience only — the LIBRARY never orchestrates docker (engine.ts is
+      // side-effect-free). This lives in the CLI: it prints (or, with --run,
+      // executes) the docker command that starts the embedding server image.
+      const dockerArgs = ["run", "-d", "-p", "8756:8756", "ghcr.io/maxgfr/codeindex-embed:latest"];
+      const oneLiner = `docker ${dockerArgs.join(" ")}`;
+      if (!have("docker")) {
+        process.stderr.write(
+          "codeindex: docker not found on PATH. Install Docker, then run:\n  " + oneLiner + "\n",
+        );
+        process.exitCode = 1;
+        return;
+      }
+      if (flags.run) {
+        process.stderr.write(`codeindex: starting embedding server → ${oneLiner}\n`);
+        const res = sh("docker", dockerArgs);
+        if (res.stdout.trim()) process.stdout.write(res.stdout.trim() + "\n"); // container id
+        if (!res.ok) {
+          process.stderr.write(res.stderr || "codeindex: docker run failed\n");
+          process.exitCode = 1;
+          return;
+        }
+        process.stderr.write(
+          "codeindex: server starting on http://localhost:8756 — then:\n" +
+            "  CODEINDEX_EMBED_ENDPOINT=http://localhost:8756 codeindex search \"<query>\" --repo . --semantic\n",
+        );
+      } else {
+        // Print the command for the user to run (default; no side effects).
+        process.stdout.write(oneLiner + "\n");
+        process.stderr.write(
+          "codeindex: run the line above to start the embedding server (or `embed serve --run`), then:\n" +
+            "  CODEINDEX_EMBED_ENDPOINT=http://localhost:8756 codeindex search \"<query>\" --repo . --semantic\n",
+        );
+      }
     } else if (sub === "build") {
       if (!flags.out) throw new Error("embed build needs --out <dir>");
       if (!modelDir) {
@@ -340,7 +417,7 @@ export async function runCli(argv: string[]): Promise<void> {
       writeFileSync(join(destDir, "model.json"), body);
       process.stderr.write(`codeindex: model written to ${join(destDir, "model.json")}\n`);
     } else {
-      throw new Error("embed needs a subcommand: pull | build | status");
+      throw new Error("embed needs a subcommand: status | build | pull | serve");
     }
   } else if (cmd === "rules") {
     if (!flags.config) throw new Error("rules needs --config <codeindex.rules.json>");

package/src/engine.ts

@@ -115,13 +115,25 @@ export {
   resolveEmbedPullUrl,
 } from "./embed/model.js";
 export type { StaticEmbedModel } from "./embed/model.js";
-export { encode, tokenize, wordpiece, basicTokenize, roundHalfToEven, intDot } from "./embed/encode.js";
-export { buildEmbeddingIndex, serializeEmbeddings, deserializeEmbeddings } from "./embed/index.js";
-export type { EmbeddingIndex, EmbeddingRecord } from "./embed/index.js";
+export { encode, quantize, tokenize, wordpiece, basicTokenize, roundHalfToEven, intDot } from "./embed/encode.js";
+export { buildEmbeddingIndex, serializeEmbeddings, deserializeEmbeddings, embeddingUnits } from "./embed/index.js";
+export type { EmbeddingIndex, EmbeddingRecord, EmbeddingUnit } from "./embed/index.js";
 export { searchSemantic } from "./embed/search.js";
 export type { SemanticSearchOptions, SemanticSearchResult } from "./embed/search.js";
-// HTTP endpoint tier (v2.11 preview — NOT wired into the CLI/MCP here).
-export { embedViaEndpoint, resolveEmbedEndpoint } from "./embed/endpoint.js";
+// HTTP endpoint tier (v2.11.0 — the "rich" tier). The engine is a fetch consumer
+// of a containerized embedding server (CODEINDEX_EMBED_ENDPOINT): float vectors
+// run through the SAME L2+int8 quantize pipeline, then the same integer ranking.
+// Deterministic PER IMAGE DIGEST (not byte-golden). The library never
+// orchestrates docker — `codeindex embed serve` (CLI) only prints/runs it.
+export {
+  embedViaEndpoint,
+  resolveEmbedEndpoint,
+  embedEndpointUrl,
+  healthzUrl,
+  probeEndpoint,
+  encodeQueryViaEndpoint,
+  buildEndpointIndex,
+} from "./embed/endpoint.js";
 export type { EmbedEndpointOptions } from "./embed/endpoint.js";
 
 // Architecture rules: forbidden edges + cycles/orphans builtins (issue #4).