@gmickel/gno 2.5.1 → 2.7.0

package/src/core/vector-partition-status.ts

@@ -0,0 +1,52 @@
+import type {
+  VectorPartitionStatus,
+  VectorRuntimeStatus,
+} from "../store/vector/status";
+
+const shortId = (id: string): string => id.slice(0, 12);
+
+function runtimeLine(runtime: VectorRuntimeStatus): string {
+  const label = runtime.label ? ` (${runtime.label})` : "";
+  if (runtime.state === "vectors")
+    return `  This runtime${label} reads ${shortId(runtime.partition ?? "")}`;
+  if (runtime.state === "unavailable")
+    return `  This runtime${label} uses lexical retrieval only: ${runtime.reason}`;
+  return "  This runtime has not resolved a partition yet; run a query or `gno embed`";
+}
+
+/**
+ * The caller's runtime, then one line per partition. The healthy case (one
+ * current partition this runtime reads) prints nothing, so default status
+ * output is unchanged.
+ */
+export function formatVectorPartitionLines(
+  partitions?: VectorPartitionStatus[],
+  runtime?: VectorRuntimeStatus
+): string[] {
+  if (!partitions?.length) return [];
+  const [only] = partitions;
+  if (
+    partitions.length === 1 &&
+    only?.retrieval &&
+    !only.legacy &&
+    !only.incompatibleRuntimes.length
+  )
+    return [];
+  const lines = ["Vector partitions:"];
+  if (runtime) lines.push(runtimeLine(runtime));
+  for (const p of partitions) {
+    const role = p.retrieval
+      ? " (used by this runtime's retrieval)"
+      : p.droppable
+        ? ` (drop with: gno vec drop ${shortId(p.id)})`
+        : "";
+    lines.push(
+      `  ${p.retrieval ? "*" : " "} ${shortId(p.id)} ${p.state}${p.legacy ? " legacy" : ""}, ${p.owners} chunks, ${p.provenance}${role}`
+    );
+    if (p.compatibleRuntimes.length)
+      lines.push(`      read by: ${p.compatibleRuntimes.join("; ")}`);
+    if (p.incompatibleRuntimes.length)
+      lines.push(`      incompatible: ${p.incompatibleRuntimes.join("; ")}`);
+  }
+  return lines;
+}

package/src/embed/backlog.ts

@@ -1,3 +1,5 @@
+import type { Database } from "bun:sqlite";
+
 import type { EmbeddingPort } from "../llm/types";
 /**
  * Shared embedding backlog processor.
@@ -12,21 +14,26 @@ import type {
   VectorStatsPort,
 } from "../store/vector";
 import type { VectorVariantStore } from "../store/vector/variants";
+import type { AcquireWriteTurn } from "./retry";
 
 import {
   assertInferenceActive,
   isBackgroundInference,
 } from "../llm/inference-scope";
+import { formatDocForEmbedding } from "../pipeline/contextual";
 import { err, ok } from "../store/types";
+import {
+  embeddingPartitionIdentity,
+  recordReferenceRuntime,
+  resolveRuntimePartition,
+} from "../store/vector/runtime-compat";
 import { getVectorStatsDatabase } from "../store/vector/stats";
 import { createVectorVariantStore } from "../store/vector/variants";
-import {
-  getEmbeddingFingerprint,
-  getVariantModelFingerprint,
-} from "./fingerprint";
+import { getEmbeddingFingerprint } from "./fingerprint";
 import {
   chunkRetryKey,
   embedAndStoreBatch,
+  inWriteTurn,
   MAX_EMBED_CHUNK_ATTEMPTS,
 } from "./retry";
 import { embedVariantBacklog } from "./variant-backlog";
@@ -47,6 +54,14 @@ export interface EmbedBacklogDeps {
   variantStore?: VectorVariantStore;
   /** Recheck the effective runtime identity after asynchronous inference. */
   identityStillCurrent?: () => boolean;
+  /**
+   * Write gate for callers that do not already hold the shared writer lease
+   * (the resident scheduler): taken around each page's writes and released
+   * after. null means another writer holds it; the pass stops as deferred.
+   */
+  acquireWriteTurn?: AcquireWriteTurn;
+  /** Explicit confirmation to build a separate vector partition (never implied by --yes). */
+  allowNewPartition?: boolean;
 }
 
 export interface EmbedBacklogResult {
@@ -59,6 +74,8 @@ export interface EmbedBacklogResult {
   contentionErrors?: number;
   /** Error message if vec index sync failed (embeddings stored, but search may be stale) */
   syncError?: string;
+  /** The pass stopped early because another writer held the write gate. */
+  deferred?: boolean;
 }
 
 interface Cursor {
@@ -78,7 +95,18 @@ export async function embedBacklog(
   deps: EmbedBacklogDeps
 ): Promise<StoreResult<EmbedBacklogResult>> {
   assertInferenceActive();
-  const prepared = await prepareEmbeddingBacklog(deps);
+  if (deps.acquireWriteTurn && !deps.variantStore) {
+    // Model loading stays outside the write turn; preparation's partition
+    // writes below take one like every other background write.
+    const initialized = await deps.embedPort.init();
+    if (!initialized.ok) return err("INTERNAL", initialized.error.message);
+  }
+  const turn = await inWriteTurn(deps.acquireWriteTurn, () =>
+    prepareEmbeddingBacklog(deps)
+  );
+  if (turn.deferred)
+    return ok({ embedded: 0, errors: 0, contentionErrors: 0, deferred: true });
+  const prepared = turn.value;
   if (!prepared.ok) return prepared;
   deps = prepared.value;
   if (deps.variantStore) return embedVariantBacklog(deps, deps.variantStore);
@@ -201,7 +229,10 @@ export async function embedBacklog(
         embedFingerprint,
         identityStillCurrent: deps.identityStillCurrent,
         statsPort,
+        acquireWriteTurn: deps.acquireWriteTurn,
       });
+      if (batchStoreResult.deferred)
+        return ok({ embedded, errors, contentionErrors, deferred: true });
       embedded += batchStoreResult.embedded;
       errors += batchStoreResult.errors;
       contentionErrors += batchStoreResult.contentionErrors;
@@ -225,7 +256,12 @@ export async function embedBacklog(
     // Sync vec index once at end if any vec0 writes failed
     let syncError: string | undefined;
     if (vectorIndex.vecDirty) {
-      const syncResult = await vectorIndex.syncVecIndex();
+      const turn = await inWriteTurn(deps.acquireWriteTurn, () =>
+        vectorIndex.syncVecIndex()
+      );
+      if (turn.deferred)
+        return ok({ embedded, errors, contentionErrors, deferred: true });
+      const syncResult = turn.value;
       if (syncResult.ok) {
         const { added, removed } = syncResult.value;
         if (added > 0 || removed > 0) {
@@ -248,6 +284,59 @@ export async function embedBacklog(
   }
 }
 
+function formatEstimate(ms: number): string {
+  const seconds = Math.max(1, Math.round(ms / 1000));
+  if (seconds < 90) return `about ${seconds} s`;
+  const minutes = Math.round(seconds / 60);
+  return minutes < 90
+    ? `about ${minutes} min`
+    : `about ${(minutes / 60).toFixed(1)} h`;
+}
+
+/** Time this port on a few current chunks when no compatibility sample ran. */
+async function measureEmbedRate(
+  db: Database,
+  port: EmbeddingPort
+): Promise<number | undefined> {
+  const inputs = db
+    .query<{ text: string; title: string | null }, []>(`
+      SELECT c.text, d.title FROM documents d
+      JOIN content_chunks c ON c.mirror_hash = d.mirror_hash
+      WHERE d.active = 1 ORDER BY d.id, c.seq LIMIT 8
+    `)
+    .all()
+    .map((row) =>
+      formatDocForEmbedding(row.text, row.title ?? undefined, port.modelUri)
+    );
+  if (!inputs.length) return undefined;
+  const startedAt = performance.now();
+  const result = await port.embedBatch(inputs);
+  return result.ok
+    ? (performance.now() - startedAt) / inputs.length
+    : undefined;
+}
+
+/** R3: a fork names itself, its full size and a measured estimate before it runs. */
+async function separatePartitionMessage(
+  db: Database,
+  port: EmbeddingPort,
+  reason: string,
+  msPerChunk: number | undefined
+): Promise<string> {
+  const chunks = db
+    .query<{ count: number }, []>(`
+      SELECT count(*) AS count FROM documents d
+      JOIN content_chunks c ON c.mirror_hash = d.mirror_hash WHERE d.active = 1
+    `)
+    .get()!.count;
+  const rate = msPerChunk ?? (await measureEmbedRate(db, port));
+  const estimate =
+    rate === undefined
+      ? "no estimate: embedding could not be timed"
+      : `estimated ${formatEstimate(rate * chunks)} at the measured ${Math.round(rate)} ms per chunk`;
+  return `Embedding would build a separate vector partition (${reason}). It re-embeds all ${chunks} chunks (${estimate}). Confirm with \`gno embed --new-partition\`; --yes alone does not confirm.`;
+}
+
 /** Resolve authority before counts, dry runs, forced work, or early returns. */
 export async function prepareEmbeddingBacklog(
   deps: EmbedBacklogDeps
@@ -259,19 +348,36 @@ export async function prepareEmbeddingBacklog(
       const initialized = await deps.embedPort.init();
       if (!initialized.ok) return err("INTERNAL", initialized.error.message);
       const identity = deps.embedPort.getIdentity?.();
-      if (identity) {
+      const primary = embeddingPartitionIdentity(deps.embedPort);
+      if (identity && primary) {
         const identitySnapshot = JSON.stringify(identity);
-        const dimensions = deps.embedPort.dimensions();
-        const variantStore = await createVectorVariantStore(db, {
-          model: deps.modelUri,
-          modelFingerprint: getVariantModelFingerprint(
-            { modelUri: deps.modelUri, dimensions },
-            identity
-          ),
-          contextSize: identity.contextSize,
-          truncationPolicy: identity.truncationPolicy,
-          dimensions,
-        });
+        const dimensions = primary.dimensions;
+        const resolved = await resolveRuntimePartition(
+          db,
+          deps.embedPort,
+          primary
+        );
+        if (resolved.blocked && !deps.allowNewPartition)
+          return err(
+            "VECTOR_PARTITION_FORK",
+            await separatePartitionMessage(
+              db,
+              deps.embedPort,
+              resolved.blocked.reason,
+              resolved.msPerChunk
+            )
+          );
+        const variantStore = await createVectorVariantStore(
+          db,
+          resolved.blocked?.separate ?? resolved.identity,
+          identity.runtimeLabel
+        );
+        if (resolved.blocked || resolved.verdict === "unverified") {
+          // Vectors without a current owner cannot be measured; they must not
+          // survive to be reused by the runtime that becomes the reference.
+          variantStore.collectGarbage();
+          recordReferenceRuntime(db, variantStore.partitionId, identity);
+        }
         variantStore.selectForEmbedding();
         return ok({
           ...deps,

package/src/embed/fingerprint.ts

@@ -36,16 +36,19 @@ export function getEmbeddingFingerprint(
     .digest("hex");
 }
 
-/** Partition provenance combines actual weights/runtime with the unchanged formatter policy. */
+/**
+ * Partition identity: actual weights plus the formatter policy. Runtime details
+ * (Bun, native binding, backend, threads) are provenance, never identity; the
+ * measured compatibility check decides whether a runtime may share vectors.
+ */
 export function getVariantModelFingerprint(
   input: EmbeddingFingerprintInput,
-  identity: { modelFingerprint: string; runtimeFingerprint: string }
+  identity: { modelFingerprint: string }
 ): string {
   return new Bun.CryptoHasher("sha256")
     .update(
       JSON.stringify([
         identity.modelFingerprint,
-        identity.runtimeFingerprint,
         getEmbeddingFingerprint(input),
       ])
     )

package/src/embed/retry.ts

@@ -15,6 +15,28 @@ import { getVectorStatsDatabase } from "../store/vector/stats";
 import { embedTextsWithRecovery } from "./batch";
 
 export const MAX_EMBED_CHUNK_ATTEMPTS = 2;
+
+/**
+ * Write gate for callers that do not already hold the shared writer lease
+ * (the resident scheduler). Returns a release, or null when another writer
+ * holds the lease.
+ */
+export type AcquireWriteTurn = () => Promise<(() => Promise<void>) | null>;
+
+/** Run `write` inside one write turn, or report that the gate is held elsewhere. */
+export async function inWriteTurn<T>(
+  acquire: AcquireWriteTurn | undefined,
+  write: () => Promise<T>
+): Promise<{ deferred: true } | { deferred: false; value: T }> {
+  if (!acquire) return { deferred: false, value: await write() };
+  const release = await acquire();
+  if (!release) return { deferred: true };
+  try {
+    return { deferred: false, value: await write() };
+  } finally {
+    await release();
+  }
+}
 export const MAX_EMBED_FAILURE_SAMPLES = 5;
 
 /** Total upsert attempts (initial + retries) when persistence hits SQLITE_BUSY/LOCKED. */
@@ -44,6 +66,8 @@ export interface EmbedStoreBatchResult {
   suggestion?: string;
   batchFailed: boolean;
   batchError?: string;
+  /** The write gate was held elsewhere; nothing was persisted. */
+  deferred?: boolean;
 }
 
 // fn-127 integration: CLI consumers (src/cli/commands/embed.ts,
@@ -173,6 +197,8 @@ export async function embedAndStoreBatch(params: {
   identityStillCurrent?: () => boolean;
   /** Test seam: override contention-retry delays in milliseconds. */
   delays?: number[];
+  /** Gate held only around persistence, never around inference. */
+  acquireWriteTurn?: AcquireWriteTurn;
 }): Promise<EmbedStoreBatchResult> {
   const { embedPort, vectorIndex, items, modelUri, embedFingerprint } = params;
   const db = params.statsPort && getVectorStatsDatabase(params.statsPort);
@@ -282,35 +308,48 @@ export async function embedAndStoreBatch(params: {
       );
     });
   };
-  const storeResult = await upsertVectorsWithContentionRetry(
-    {
-      upsertVectors: async (rows) => {
-        if (vectorIndex.upsertVectorsChecked) {
-          const result = await vectorIndex.upsertVectorsChecked(
-            rows,
-            (candidates) => {
-              committedRows = checkpoint(candidates);
-              return committedRows;
-            }
-          );
-          if (!result.ok) return result;
-          written = result.value;
-          return ok(undefined);
-        }
-        if (db)
-          return err("INVALID_INPUT", "Atomic vector checkpoint unavailable");
-        const valid = checkpoint(rows);
-        const result = await vectorIndex.upsertVectors(valid);
-        if (result.ok) {
-          written = valid.length;
-          committedRows = valid;
-        }
-        return result;
+  const turn = await inWriteTurn(params.acquireWriteTurn, () =>
+    upsertVectorsWithContentionRetry(
+      {
+        upsertVectors: async (rows) => {
+          if (vectorIndex.upsertVectorsChecked) {
+            const result = await vectorIndex.upsertVectorsChecked(
+              rows,
+              (candidates) => {
+                committedRows = checkpoint(candidates);
+                return committedRows;
+              }
+            );
+            if (!result.ok) return result;
+            written = result.value;
+            return ok(undefined);
+          }
+          if (db)
+            return err("INVALID_INPUT", "Atomic vector checkpoint unavailable");
+          const valid = checkpoint(rows);
+          const result = await vectorIndex.upsertVectors(valid);
+          if (result.ok) {
+            written = valid.length;
+            committedRows = valid;
+          }
+          return result;
+        },
       },
-    },
-    vectors,
-    params.delays
+      vectors,
+      params.delays
+    )
   );
+  if (turn.deferred)
+    return {
+      embedded: 0,
+      errors: 0,
+      contentionErrors: 0,
+      retryItems: [],
+      errorSamples: [],
+      batchFailed: false,
+      deferred: true,
+    };
+  const storeResult = turn.value;
   if (!storeResult.ok) {
     if (isUpsertLockContention(storeResult.error)) {
       return {

package/src/embed/variant-backlog.ts

@@ -8,6 +8,7 @@ import {
 } from "../llm/inference-scope";
 import { err, ok } from "../store/types";
 import { getVectorStatsDatabase } from "../store/vector/stats";
+import { inWriteTurn } from "./retry";
 import { variantBacklogPage } from "./variant-plan";
 import { embedVariantBatch } from "./variant-retry";
 
@@ -59,7 +60,9 @@ export async function embedVariantBacklog(
         owners,
         identityStillCurrent,
         force: deps.force,
+        acquireWriteTurn: deps.acquireWriteTurn,
       });
+      if (result.deferred) return ok({ ...total, deferred: true });
       total.embedded += result.embedded;
       total.errors += result.errors;
       total.contentionErrors += result.contentionErrors;
@@ -83,16 +86,18 @@ export async function embedVariantBacklog(
     // Capture the epoch before checking completeness; activate rechecks under write lock.
     const epoch = store.epoch();
     if (identityStillCurrent() && !store.pending({ limit: 1 }).length) {
-      try {
-        if (!store.isActive()) store.syncIndex();
-        if (!identityStillCurrent()) return ok(total);
-        store.activate(epoch);
-      } catch (cause) {
-        return ok({
-          ...total,
-          syncError: cause instanceof Error ? cause.message : String(cause),
-        });
-      }
+      const turn = await inWriteTurn(deps.acquireWriteTurn, async () => {
+        try {
+          if (!store.isActive()) store.syncIndex();
+          if (identityStillCurrent()) store.activate(epoch);
+          return undefined;
+        } catch (cause) {
+          return cause instanceof Error ? cause.message : String(cause);
+        }
+      });
+      if (turn.deferred) return ok({ ...total, deferred: true });
+      if (turn.value !== undefined)
+        return ok({ ...total, syncError: turn.value });
     }
     assertInferenceActive();
     return ok(total);

package/src/embed/variant-retry.ts

@@ -5,7 +5,9 @@ import type { VectorVariantStore } from "../store/vector/variants";
 import { err, ok } from "../store/types";
 import { embedTextsWithRecovery } from "./batch";
 import {
+  type AcquireWriteTurn,
   chunkRetryKey,
+  inWriteTurn,
   isUpsertLockContention,
   upsertVectorsWithContentionRetry,
 } from "./retry";
@@ -30,11 +32,14 @@ export async function embedVariantBatch(params: {
   identityStillCurrent: () => boolean;
   delays?: number[];
   force?: boolean;
+  /** Gate held only around the checkpoint write, never around inference. */
+  acquireWriteTurn?: AcquireWriteTurn;
 }): Promise<{
   embedded: number;
   errors: number;
   contentionErrors: number;
   retryOwners: VectorOwnerInput[];
+  deferred?: boolean;
 }> {
   const { store, embedPort, identityStillCurrent } = params;
   const empty = {
@@ -76,30 +81,34 @@ export async function embedVariantBatch(params: {
     .map((owner) => ({ owner, embedding: vectors.get(owner.inputHash) }));
   if (!rows.length) return { ...empty, retryOwners };
   let written = 0;
-  const persisted = await upsertVectorsWithContentionRetry(
-    {
-      upsertVectors: () => {
-        try {
-          // A contention wait may allow document or runtime mutations. Revalidate each attempt.
-          if (!identityStillCurrent()) return Promise.resolve(ok(undefined));
-          const valid = rows.filter(({ owner }) => isCurrent(store, owner));
-          store.write(valid);
-          written = valid.length;
-          return Promise.resolve(ok(undefined));
-        } catch (cause) {
-          return Promise.resolve(
-            err(
-              "QUERY_FAILED",
-              cause instanceof Error ? cause.message : String(cause),
-              cause
-            )
-          );
-        }
+  const turn = await inWriteTurn(params.acquireWriteTurn, () =>
+    upsertVectorsWithContentionRetry(
+      {
+        upsertVectors: () => {
+          try {
+            // A contention wait may allow document or runtime mutations. Revalidate each attempt.
+            if (!identityStillCurrent()) return Promise.resolve(ok(undefined));
+            const valid = rows.filter(({ owner }) => isCurrent(store, owner));
+            store.write(valid);
+            written = valid.length;
+            return Promise.resolve(ok(undefined));
+          } catch (cause) {
+            return Promise.resolve(
+              err(
+                "QUERY_FAILED",
+                cause instanceof Error ? cause.message : String(cause),
+                cause
+              )
+            );
+          }
+        },
       },
-    },
-    [],
-    params.delays
+      [],
+      params.delays
+    )
   );
+  if (turn.deferred) return { ...empty, deferred: true };
+  const persisted = turn.value;
   if (!persisted.ok)
     return {
       ...empty,

package/src/index.ts

@@ -8,15 +8,35 @@
 
 import { runCli } from "./cli/run";
 import { resetModelManager } from "./llm/nodeLlamaCpp/lifecycle";
+import { IMPORT_CHILD_ENV } from "./sessions/import-child-env";
 
 /**
- * Cleanup models and exit.
- * Without this, llama.cpp native threads can keep the process alive.
+ * End `stream` and resolve once its queued writes have reached the OS.
+ * process.exit() drops pending asynchronous pipe writes, so a pipe consumer
+ * would otherwise see output cut at the pipe buffer size. Bun reports no
+ * writableLength and fires an empty write's callback immediately, so end()
+ * is the flush that actually waits. A closed consumer (EPIPE) settles
+ * through the callback or the 'error' event.
+ */
+function flushStream(stream: NodeJS.WriteStream): Promise<void> {
+  if (stream.destroyed || stream.writableEnded) {
+    return Promise.resolve();
+  }
+  return new Promise((resolve) => {
+    stream.once("error", () => resolve());
+    stream.end(() => resolve());
+  });
+}
+
+/**
+ * Cleanup models, flush output, and exit.
+ * Without the explicit exit, llama.cpp native threads can keep the process alive.
  */
 async function cleanupAndExit(code: number): Promise<never> {
   await resetModelManager().catch(() => {
     // Ignore cleanup errors on exit
   });
+  await Promise.all([flushStream(process.stdout), flushStream(process.stderr)]);
   process.exit(code);
 }
 
@@ -37,6 +57,14 @@ process.on("SIGINT", () => {
   });
 });
 
+// A compiled executable re-run as the session import child (see
+// src/sessions/import-child.ts) serves that one request instead of the CLI.
+if (process.env[IMPORT_CHILD_ENV] === "1") {
+  const { runImportChild } = await import("./sessions/import-child");
+  await runImportChild();
+  await cleanupAndExit(0);
+}
+
 // Await module completion so pending piped stdin keeps Windows Bun alive.
 await runCli(process.argv)
   .then((code) => cleanupAndExit(interruptExitCode || code))

package/src/llm/native-worker/dispatcher.ts

@@ -15,6 +15,7 @@ import {
   fileIdentity,
   fingerprintModel,
   fingerprintRuntime,
+  runtimeLabel,
 } from "./embedding-identity";
 import { NativeWorkerError } from "./errors";
 import { checkEvaluation } from "./evaluation";
@@ -174,6 +175,7 @@ export class NativeDispatcher {
                   gpu: llama.gpu,
                   cpuMathCores: llama.cpuMathCores,
                 }),
+                runtimeLabel: runtimeLabel(llama.gpu),
               },
             },
           };

package/src/llm/native-worker/embedding-identity.ts

@@ -31,3 +31,45 @@ export function fingerprintRuntime(settings: Record<string, unknown>): string {
     )
     .digest("hex");
 }
+
+/** Environment that shapes the native runtime identity of an embedding. */
+const RUNTIME_ENV = [
+  "GNO_LLAMA_GPU",
+  "NODE_LLAMA_CPP_GPU",
+  "GNO_EMBED_CONTEXT_SIZE",
+  "GNO_EMBED_CONTEXTS",
+  "GNO_EMBED_THREADS",
+] as const;
+
+/**
+ * What a process can know about its embedding runtime without loading the
+ * model: status looks up the identity a caller with this key last resolved.
+ */
+export function runtimeCallerKey(
+  model: string,
+  env: NodeJS.ProcessEnv = process.env
+): string {
+  return new Bun.CryptoHasher("sha256")
+    .update(
+      JSON.stringify([
+        model,
+        Bun.version,
+        nativePackage.version,
+        process.platform,
+        process.arch,
+        RUNTIME_ENV.map((name) => env[name] ?? null),
+      ])
+    )
+    .digest("hex");
+}
+
+const BACKEND_LABELS: Record<string, string> = {
+  cuda: "CUDA",
+  metal: "Metal",
+  vulkan: "Vulkan",
+};
+
+/** Readable provenance for status output; identity stays the fingerprint. */
+export function runtimeLabel(gpu: string | false): string {
+  return `${gpu ? (BACKEND_LABELS[gpu] ?? gpu) : "CPU"}, Bun ${Bun.version}`;
+}

package/src/llm/native-worker/protocol.ts

@@ -112,6 +112,7 @@ export const EmbeddingIdentitySchema = z.strictObject({
   truncationPolicy: z.string().min(1),
   modelFingerprint: z.string().regex(/^[a-f0-9]{64}$/),
   runtimeFingerprint: z.string().regex(/^[a-f0-9]{64}$/),
+  runtimeLabel: z.string().min(1),
 });
 const metadata = z.strictObject({
   dimensions: id.optional(),

package/src/llm/types.ts

@@ -95,7 +95,10 @@ export interface EmbeddingIdentity {
   /** Versioned policy including the effective token limit. */
   truncationPolicy: string;
   modelFingerprint: string;
+  /** Runtime provenance (Bun, binding, backend, threads); not vector identity. */
   runtimeFingerprint: string;
+  /** Readable provenance such as "CUDA, Bun 1.4.2". */
+  runtimeLabel?: string;
 }
 
 export interface EmbeddingPort {